Skip to content

Script API

Everything your script can call, imported from the siphon package the addon mounts its namespaces onto:

import siphon
from siphon import ss7, gsm_map, gsm_cap, inap

There are four groups: the ss7 routing namespace (live tables); the gsm_map / gsm_cap / inap termination decorators, result builders, and invoke builders; the Dialogue handle a termination handler drives; and the decoded views a handler receives. Handlers may be async def; they run to completion on SIPhon's runtime. For unit-testing a script off the wire, see Testing your handlers.

The node

The composing siphon binary owns the node. At startup it reads its extensions.sigtran config and builds the process-wide node, then loads your script (see Using it in a SIPhon build). A script does not configure the node; it just imports the namespaces and programs them. The config is sigtran.yaml.

ss7.metrics() renders the Prometheus text exposition for the whole node (see Routing model & coverage). It is on the ss7 namespace because siphon.metrics is SIPhon's own.

ss7

The routing namespace. It programs the Rust routing tables live.

Live tables

Call Effect
ss7.routes.add(dpc, as_=…\|linkset=…, priority=1) Add or extend an MTP3 route. Name exactly one of as_ / linkset.
ss7.routes.cache(gt, dpc=…, ssn=…, ttl=None) Cache a translation as a GTT prefix rule, so later MSUs for gt route in Rust. ttl is accepted for API stability; the rule persists until reprogrammed.
ss7.gtt.add(match={…}, to={…}) Prepend a GTT rule. match / to are dicts mirroring the config gtt schema.
ss7.content.add_rule(name, match={…}, action={…}) Prepend a content rule (config content_routing schema).
ss7.content.address_table(name).add(gt) Add a GT digit string to an address table live, creating it if absent. Idempotent.
ss7.gt(digits, ssn=None) Build an SCCP Address (E.164, GTI-4).
ss7.metrics() The Prometheus text exposition for the whole node.

Prepending means a live rule wins over the static config rules (first match wins). Programming a table at script load keeps every subsequent decision in Rust at line rate. A content rule's action is route, rewrite_cdpa_gt, or screen (see content_routing).

gsm_map

MAP (TS 29.002): termination decorators plus result and invoke builders. Termination decorators register a handler for their operation on every owned SSN (sccp.local_ssns), so the handler fires whichever subsystem the message was addressed to.

Terminating operations: @gsm_map.on_operation

@gsm_map.on_operation("<name>") registers a handler for one or more MAP operations, named by their kebab-case operation name, the same on_<message>("<name>") shape as the sibling @smpp.on_pdu. As with the SIP proxy's @proxy.on_request, a handler can take several operations pipe-separated, and a bare decorator is a catch-all over every MAP operation.

@gsm_map.on_operation("mo-forward-sm")                # one operation
@gsm_map.on_operation("mo-forward-sm|mt-forward-sm")  # several, pipe-separated
@gsm_map.on_operation                                 # bare: every MAP operation

A handler registers on every owned SSN (sccp.local_ssns), so it fires whichever subsystem the message was addressed to. An unknown operation name raises SigtranError at decoration time. The selector names:

Name Operation Op code
mo-forward-sm MO-ForwardSM 46
mt-forward-sm MT-ForwardSM 44
sri-sm SendRoutingInfoForSM 45
report-sm-delivery-status reportSM-DeliveryStatus 47
ready-for-sm readyForSM 66
update-location updateLocation 2
cancel-location cancelLocation 3
purge-ms purgeMS 67
send-auth-info sendAuthenticationInfo 56
provide-subscriber-info provideSubscriberInfo 70

mo-forward-sm also covers the legacy forwardSM

Op code 46 is both v3 mo-forwardSM and the v1/v2 combined forwardSM, so a mo-forward-sm handler receives a legacy forwardSM(46) as well; mt-forwardSM is a distinct op (44). The MAP version and, for a v1/v2 forwardSM, the MO/MT direction live in the TCAP application context and the SM-RP-DA/OA, not the op code, so the op-code-keyed dispatch does not split on them.

On the opening leg the handler is def on(dlg, arg) where dlg is a Dialogue and arg is the decoded IncomingOp. On a follow-up leg of a held-open dialogue the same handler is re-entered with a PeerTurn in place of arg; branch on arg.is_peer_turn. See the HLR held-open flow.

Result builders

Each returns a Result to dlg.reply(...) with. It builds and encodes the real MAP result argument.

Call Result
gsm_map.mo_forward_sm_res() MO-ForwardSM ack.
gsm_map.mt_forward_sm_res() MT-ForwardSM ack.
gsm_map.send_routing_info_for_sm_res(imsi=…, network_node_number=…, lmsi=None) SRI-SM: the recipient IMSI and serving MSC/SGSN.
gsm_map.update_location_res(hlr_number=…) updateLocation: the HLR number.
gsm_map.send_authentication_info_res(quintuplets=None, triplets=None) Authentication vectors (each quintuplet (rand, xres, ck, ik, autn), each triplet (rand, sres, kc)).
gsm_map.insert_subscriber_data_res() The VLR accepting pushed subscriber data.
gsm_map.cancel_location_res() cancelLocation ack.
gsm_map.purge_ms_res(freeze_tmsi=False, freeze_p_tmsi=False) purgeMS ack.
gsm_map.ready_for_sm_res() readyForSM ack.

Invoke builders and helpers

Call Returns / effect
gsm_map.insert_subscriber_data(imsi=None, msisdn=None) A staged Invoke: the HLR pushing subscriber data inside a held-open updateLocation.
gsm_map.mt_forward_sm(imsi=…, sc_addr=…, tpdu=…, more_messages_to_send=False) A staged Invoke to dlg.invoke(...). Set more_messages_to_send on all but the last segment.
gsm_map.mo_forward_sm(sc_addr=…, msisdn=…, tpdu=…, imsi=None) A staged Invoke: relay a mobile-originated TPDU on to the service centre.
gsm_map.AC.short_msg_mt_relay / .short_msg_gateway / .short_msg_mo_relay MAP application-context handles (version 3).

The address arguments (sc_addr, msisdn, hlr_number, network_node_number, imsi, a CAP destination_routing_address) take an E.164 digit string and are encoded for you (TBCD for MAP AddressStrings, Q.763 for the CAP called party), exactly as ss7.gt does; a raw already-encoded bytes is also accepted (e.g. a value decoded off the wire). The tpdu= argument of mt_forward_sm / mo_forward_sm is different: it is an opaque SMS transfer-layer PDU that siphon-sigtran never inspects, built with the tpdu crate. See Building an SMSC.

gsm_cap

CAMEL CAP (TS 29.078). Termination via @gsm_cap.on_operation("<name>") (the same shape as @gsm_map.on_operation), then the gsmSCF invoke builders an SCP stages toward the gsmSSF.

Name Operation Op code
initial-dp A CAMEL initialDP. Handler is def on(dlg, idp), idp a decoded IncomingOp (with .service_key, .imsi, .calling_party_number, .event_type_bcsm, .location_information and the rest). 0
event-report-bcsm An EventReportBCSM the gsmSSF sends when an armed detection point fires. 24
Invoke builder Stages
gsm_cap.connect(destination_routing_address=[…], original_called_party_id=None) Connect: reroute the call. The list holds the one called-party number TS 29.078 allows, an E.164 digit string or raw bytes.
gsm_cap.release_call(cause=…) ReleaseCall: tear the call down with a Q.850 cause.
gsm_cap.request_report_bcsm_event(events=[…]) RequestReportBCSMEvent: arm detection points. Each event is (event_type, monitor_mode) or (event_type, monitor_mode, leg) (integers per TS 29.078); the leg goes out as legID [2] { sendingSideID [0] }. A disconnect is armed per leg.
gsm_cap.apply_charging(max_call_period_duration=…, release_if_duration_exceeded=None, tariff_switch_interval=None, tone=None, party_to_charge=None, phase=None) ApplyCharging with time-duration charging: a call period in units of 100 ms, metered on leg party_to_charge. See below for the CAMEL phase. charging_characteristics= takes an already encoded CAMEL-AChBillingChargingCharacteristics value in place of the typed keywords.
gsm_cap.continue_() Continue: let the call proceed.

Stage several in one dialogue (a RequestReportBCSMEvent then a Connect) with repeated dlg.invoke(...), then dlg.end(). See Building a CAMEL SCP.

ApplyCharging and the CAMEL phase. The charging characteristics are not the same octets in CAMEL phase 3 and phase 4 (the warning tone is tone [3] BOOLEAN in one and audibleIndicator [3], a constructed choice, in the other), and a gsmSSF reads the form of the phase its dialogue runs under. So the typed apply_charging is encoded when it is staged on a dialogue, from that dialogue's application context: phase 3 under 0.4.0.0.1.21.3.x, phase 4 under 0.4.0.0.1.23.3.x. Under any other context (phase 1 and 2 have another form again, which is not modelled) it cannot be encoded: the turn's answer is dropped as a whole, logged as an error, and a Begin left unanswered that way is aborted, so a call is not let through without its charging instruction. phase=3 or phase=4 fixes the phase regardless of the context.

A script sees the phase before it decides: dlg.camel_phase is 1 to 4. Under phase 2 (0.4.0.0.1.0.50.1), where the warning tone sits inside releaseIfdurationExceeded [1], a SEQUENCE (GSM 09.78 clause 6.3), the typed keywords are not available because the gsm_cap codec has no type for that form; charging_characteristics= carries the octets a script has for it.

gsm_cap.AC.gsm_ssf_scf is the phase 3 generic context (0.4.0.0.1.21.3.4), gsm_cap.AC.gsm_ssf_scf_phase4 the phase 4 one (0.4.0.0.1.23.3.4).

The InitialDP getters decode the argument strictly and raise MistypedParameter when it does not decode. A mobile-originated call carries what was dialled in called_party_bcd_number; called_party_number is there on forwarded and terminating calls. The whole list is under IncomingOp.

The reports that follow an InitialDP in the same dialogue (EventReportBCSM, ApplyChargingReport) come to the InitialDP's handler as the components of a PeerTurn, and each Component has a typed view of them: component.event_report_bcsm and component.apply_charging_report.

inap

INAP CS-1 (ITU-T Q.1218), the fixed-network TCAP-user peer to CAMEL. Termination via @inap.on_operation("<name>"), the same shape as @gsm_map.on_operation; an initial-dp handler reads the decoded argument off the IncomingOp inap_* getters (inap_service_key, inap_called_party_number, …).

Name Operation Op code
initial-dp InitialDP: the SSF reports a triggered call 0
event-report-bcsm EventReportBCSM: an armed detection point fired 24
apply-charging-report ApplyChargingReport: metered call result 36
assist-request-instructions AssistRequestInstructions 16
call-information-report CallInformationReport 44
specialized-resource-report SpecializedResourceReport 49

The SCF invoke builders an SCP stages toward the SSF stage the same way as gsm_cap's:

Call Stages
inap.connect(destination_routing_address=[…], original_called_party_id=None) Connect. ETS 300 374-1 allows one destination, Q.1218 up to three.
inap.request_report_bcsm_event(events=[…]) RequestReportBCSMEvent. Each event is (event_type_bcsm, monitor_mode) or (event_type_bcsm, monitor_mode, leg); the leg goes out as legID [2] { sendingSideID [0] }. Event types 1 to 18 of Q.1218, including origAttemptAuthorized (1), oMidCall (8) and tMidCall (16).
inap.apply_charging(charging_characteristics=…, party_to_charge=None) ApplyCharging.
inap.release_call(cause=…) ReleaseCall with a Q.850 cause.
inap.continue_() Continue.
inap.play_announcement(message_id=… \| tone_id=…, tone_duration=… \| information_to_send=…) PlayAnnouncement. What to send is a typed choice: an elementary announcement id, a tone, or the BER of an InformationToSend value (decoded and refused if it is not one).
inap.prompt_and_collect_user_information(maximum_digits=…, minimum_digits=None \| collected_info=…, …) PromptAndCollectUserInformation, with an optional prompt given as for play_announcement.
inap.connect_to_resource(ip_routing_address=None) ConnectToResource, to that address or to the SRF colocated with the SSF.

inap.AC supplies the application contexts of ETS 300 374-1 clause 6.5: inap.AC.ssp_to_scp (0.4.0.1.1.1.0.0), inap.AC.assist_handoff_ssp_to_scp (0.4.0.1.1.1.1.0) and inap.AC.ip_to_scp (0.4.0.1.1.1.2.0). A terminated dialogue answers with the context the SSF proposed.

The inap_* getters decode the InitialDP strictly and raise MistypedParameter when it does not decode: a member that cannot be read, a member the argument does not have, a missing serviceKey.

The Dialogue handle

Passed to every termination handler. The handler stages components and then flushes them; the engine replays the staged commands onto the real Rust dialogue and encodes the wire TCAP, so the handler's view stays simple and the encoding stays in Rust.

Method Stages / does
dlg.invoke(staged, *, operation_class=None, timeout=None) Stage an Invoke from an invoke builder (gsm_map.insert_subscriber_data(...), gsm_cap.connect(...)), e.g. the ISD leg of a held-open updateLocation. The builder knows the class of its operation (staged.operation_class); operation_class= (1 to 4) overrides it, timeout= is the invocation timer in seconds (default tcap.invoke_timer_ms).
dlg.reply(result) Stage a ReturnResultLast answering the opening invoke.
dlg.reply_to(invoke_id, result) Stage a result answering a specific invoke id.
dlg.error(invoke_id, error_code) Stage a ReturnError: the operation failed.
dlg.reject(invoke_id, problem_class, problem_code) Stage a Reject: the component the peer sent is a protocol error. problem_class is general / invoke / return-result / return-error, problem_code the code within it (Q.773 Tables 26 to 29). An Invoke whose argument does not decode is dlg.reject(arg.invoke_id, "invoke", 2), mistyped parameter.
dlg.set_idle_timeout(seconds) How long this dialogue may go without a message before the node aborts it, overriding tcap.dialogue_timer_ms. None waits until the peer ends it.
dlg.send() Flush as a Continue (dialogue stays open).
dlg.end() Flush as an End (dialogue closes).
dlg.abort() Abort as the dialogue's user: a U-Abort, carrying an ABRT (dialogue-service-user) when the dialogue has an application context.

dlg.otid and dlg.dtid expose the originating and peer transaction ids as bytes. dlg.application_context is the application context of the dialogue as the arcs of its object identifier, a tuple such as (0, 4, 0, 0, 1, 21, 3, 4), or None for a dialogue that has none; dlg.camel_phase is the CAMEL phase that context belongs to, 1 to 4, or None when it is not a CAP context. Both are None on the turn that tells the script a dialogue is gone (turn.closed). In-process termination (reply / invoke / send / end) needs no transport and is exercised by node.deliver.

Invoke ids are INTEGER (-128..127): reply_to, error and reject raise SigtranError for anything else. A flush the encoder refuses (a parameter that is not one BER element, say) is logged at error level with the dialogue's transaction ids and counted in sigtran_tcap_send_errors_total; when that leaves a Begin unanswered the node aborts the dialogue, so the peer is told instead of waiting.

Operation classes and timers

Every invoke has a class (Q.774 Table 2) that says which outcomes its performer reports, and an invocation timer.

Class Reports When the timer expires
1 success and failure No reply came: an abnormal situation. The handler is called with a PeerTurn whose is_timeout is true. If it stages nothing the node aborts the dialogue (a U-Abort); staging an answer (dlg.error(...), dlg.end(), dlg.send()) keeps or closes it as the script decides.
2 failure only The operation succeeded. The handler is told (is_timeout, operation_class == 2) and the dialogue goes on.
3 success only The operation failed. Told the same way; the dialogue goes on.
4 nothing Nothing is reported.

The MAP builders are class 1. The CAP and INAP builders carry the class of their operation: connect, request_report_bcsm_event, apply_charging, play_announcement and connect_to_resource are class 2, prompt_and_collect_user_information is class 1, continue_ and release_call are class 4.

A handler that stages nothing on a follow-up leg leaves the dialogue open: an SCP that armed a detection point simply waits for the next event. Give such a dialogue the idle timeout the call can last (dlg.set_idle_timeout(...)); the default tcap.dialogue_timer_ms is sized for request / response dialogues.

Decoded views

IncomingOp

The decoded opening operation a termination handler receives as its second argument (arg / idp).

Field / getter Meaning
operation_code The local MAP/CAP operation code.
invoke_id The invoke id the peer used.
calling_gt / called_gt Calling / called global-title digits, if present.
argument The raw BER argument bytes, if the Invoke carried a parameter.
further Every other component of the Begin, in order, as Component objects. Empty for the usual single Invoke.
sm_rp_oa / sm_rp_da / sm_rp_ui For MO-ForwardSM (46) and MT-ForwardSM (44): the originating address, destination address, and TPDU bytes. None for any other operation. Raise MistypedParameter when the argument does not decode.
service_key / called_party_bcd_number / called_party_number For a CAMEL initialDP: the service key, the dialled number of a mobile-originated call (type of number and plan, then TBCD digits), and the called party number of a forwarded or terminating call. None for any other operation, or when the InitialDP carries none. Raise MistypedParameter when the argument does not decode.

The members of a CAMEL initialDP

Every getter below follows the three above: None for another operation or an absent member, MistypedParameter when the argument does not decode (TS 29.078 clause 6.1.1, InitialDPArg). Numbers that have a format of their own (Q.763, TS 24.008) are the octets as received; the two TBCD strings that only hold digits are given as digits, the way the builders take them.

Getter Member Value
imsi iMSI [50] Digits, "001010000000001".
calling_party_number callingPartyNumber [3] Octets of a Q.763 calling party number.
calling_partys_category callingPartysCategory [5] Integer (Q.763); 10 is an ordinary subscriber.
event_type_bcsm eventTypeBCSM [28] Integer: 2 collectedInfo (originating), 12 termAttemptAuthorized (terminating), ...
subscriber_state subscriberState [51] assumed-idle, camel-busy, net-det-not-reachable or not-provided-from-vlr.
not_reachable_reason the same member For net-det-not-reachable: ms-purged, imsi-detached, restricted-area or not-registered.
location_information locationInformation [52] A LocationInformation, below.
ext_basic_service_code ext-basicServiceCode [53] (kind, octets), kind being bearer-service or teleservice.
call_reference_number callReferenceNumber [54] Octets. With msc_address it identifies the call (TS 23.078 clause 4.6.1.8).
msc_address mscAddress [55] Digits, "15550180".
time_and_timezone timeAndTimezone [57] Eight octets: date and time in BCD with swapped nibbles, then the time zone.
call_forwarding_ss_pending callForwardingSS-Pending [58] True when present. False for another operation.
original_called_party_id originalCalledPartyID [12] Octets (Q.763), on a forwarded call.
redirecting_party_id redirectingPartyID [29] Octets (Q.763), on a forwarded call.
redirection_information redirectionInformation [30] Two octets (Q.763).
gmsc_address gmscAddress [0] of initialDPArgExtension [59] Digits, on a terminating or forwarded call.

LocationInformation (TS 29.002) has age_of_location (minutes since the last contact, 0 while in contact), vlr_number and msc_number (digits), location_number (octets, Q.763), cell_global_id (seven octets: MCC and MNC, location area code, cell identity), location_area_id (five octets: what the argument carries as a location area, or the first five octets of the cell identity), geographical_information (octets), sai_present (the cell identity is a service area identity) and current_location_retrieved.

A digit getter (imsi, msc_address, gmsc_address, vlr_number, msc_number) raises MistypedParameter when the string holds something that is not a decimal digit before its end: a wrong subscriber is worse than none.

sm_rp_ui is an opaque SMS TPDU

siphon-sigtran handles the MAP and transaction layers; it does not decode the SMS content. sm_rp_ui (and the tpdu= argument of gsm_map.mt_forward_sm) is the raw SMS transfer-layer PDU. To read or build it (SMS-SUBMIT / SMS-DELIVER per 3GPP TS 23.040, GSM 7-bit packing per TS 23.038, the User-Data-Header for concatenation, TON/NPI addresses), use the sibling tpdu crate, which also ships as a Python wheel. See Building an SMSC.

An argument that does not decode

The decoded getters read the argument strictly. A member that is on the wire and cannot be read, a list element that cannot be read, or a missing mandatory member is an error, never a field that reads as absent; a member a later release of the protocol added after an extension marker is skipped, as TS 29.002 17.1.4 requires of a receiver. When the argument does not decode the getter raises siphon.MistypedParameter (a SigtranError).

Let it propagate and the node answers for the script: the component is rejected (Reject, mistyped parameter: invoke problem 2 for an Invoke, return-result problem 2 for a result) in an End, and whatever the handler had staged is discarded. The Reject names the first component of the turn, unless the exception came from a typed view of one component (component.event_report_bcsm, component.apply_charging_report): that one carries the invoke id of its component as error.invoke_id, and the Reject names it. Catch the exception to decide otherwise:

@gsm_map.on_operation("mo-forward-sm")
async def on_mo(dlg, arg):
    try:
        tpdu = arg.sm_rp_ui
    except siphon.MistypedParameter:
        dlg.reject(arg.invoke_id, "invoke", 2)   # what the node does by default
        dlg.end()
        return
    ...

A handler that raises anything else has staged nothing, and a Begin left unanswered that way is aborted.

PeerTurn

On a follow-up leg of a held-open dialogue the termination handler is re-entered with a PeerTurn in place of the IncomingOp: the decoded view of what the peer sent back (its Continue or End). Tell the two apart with is_peer_turn (false on the opening IncomingOp, true here). See the HLR held-open flow.

Field / getter Meaning
is_peer_turn Always True (the opening IncomingOp is False).
is_end The dialogue is over: the peer closed it with a TCAP End, or it ended otherwise (closed).
is_result / is_invoke / is_error Whether the turn carries a result, an invoke, a returnError.
operation_code The operation code of the first component (a result echoes the one it answers).
invoke_id The invoke id of the first component.
error_code The MAP/CAP error code, if the peer sent a returnError.
result The raw BER result parameter of the first returnResultLast, if present.
argument The raw BER argument of the first Invoke the peer sent, if present.
components Every component of the turn, in order, as Component objects.
is_reject The turn carries a Reject. A Reject is a protocol error, not a MAP/CAP error: is_error is false and error_code is None.
reject_is_local The Reject was raised by this node for a component of the peer's that could not be read or did not fit the dialogue. It is sent with the next send() / end(); components after an unreadable one were discarded.
reject_invoke_id The invoke id the Reject names, None if it could not be derived.
reject_problem_class / reject_problem_code / reject_problem_name The typed problem: the class (general / invoke / return-result / return-error), the code within it, and the name Q.773 gives it (mistypedParameter).
is_timeout Not a message: the invocation timer of one of our invokes expired. invoke_id, operation_code and operation_class name it. See operation classes.
closed Not a message: the dialogue ended without the script ending it. peer-abort, provider-abort (a damaged message arrived for it), abnormal-dialogue, invoke-timeout, idle-timeout, no-answer (the handler answered nothing to a Begin) or not-sent. Told exactly once; nothing can be sent any more.
is_abort closed is set.
abort_kind p-abort (a transaction sub-layer aborted) or u-abort (a TC-user or a component sub-layer did); None if no Abort message was involved.
p_abort_cause The P-Abort cause value (0 unrecognized message type, 1 unrecognized transaction ID, 2 badly formatted transaction portion, 3 incorrect transaction portion, 4 resource limitation).
abort_cause What the abort carried, as a fixed label: a P-Abort cause name, or none, dialogue-service-user, abnormal-dialogue, no-common-dialogue-portion, application-context-not-supported, dialogue-refused, user-defined.

A handler written before these existed keeps working: a turn that is a timeout or a closure has no components, so is_result / is_invoke / is_error are all false. Release whatever the script tied to the dialogue (a charging session, a pending delivery) when closed is set or is_end is true.

Component

One component of a turn (turn.components, arg.further).

Field Meaning
kind invoke, result, error, reject (from the peer) or local-reject (raised here).
invoke_id The invoke id; None only for a reject whose invoke id could not be derived.
operation_code Of an invoke, or the one a result echoes.
parameter The raw BER argument of an invoke or parameter of a result.
error_code Of an error.
problem_class / problem_code / problem_name Of a reject.
event_report_bcsm A CAMEL EventReportBCSM, decoded, when the component is an Invoke of operation 24; None otherwise. Raises MistypedParameter when the argument does not decode.
apply_charging_report A CAMEL ApplyChargingReport, decoded, when the component is an Invoke of operation 36; None otherwise. Raises the same way.

Both views are CAMEL's (TS 29.078). An INAP dialogue carries the same operation codes with other argument types, so read those from parameter.

EventReportBcsm

TS 29.078 clause 6.1.1, EventReportBCSMArg.

Getter Meaning
event_type eventTypeBCSM: the detection point, by the number request_report_bcsm_event arms it with (7 oAnswer, 9 oDisconnect, ...).
leg legID: the leg the event happened on, 1 or 2, or None.
message_type / is_request miscCallInfo.messageType: request when the detection point was armed as interrupted, so the call waits for an instruction (answer with continue_, connect or release_call); notification when it goes on and there is nothing to answer. A report without the member is a request, its default.
specific_info Which alternative of eventSpecificInformationBCSM is there: o-answer, t-answer, o-disconnect, t-disconnect, o-called-party-busy, t-busy, o-no-answer, t-no-answer, route-select-failure, o-abandon, ... or None.
release_cause Of a disconnect: the octets of a Q.850 cause.
busy_cause Of oCalledPartyBusy or tBusy.
failure_cause Of routeSelectFailure.
destination_address / or_call / forwarded_call / charge_indicator Of an answer.
call_forwarded / forwarding_destination_number Of tBusy or tNoAnswer.
route_not_permitted Of tBusy or oAbandon.

The octet getters are None, and the flags False, on an event that does not carry them.

ApplyChargingReport

The timeDurationChargingResult of the CAMEL-CallResult inside the argument (TS 29.078 clause 5.1).

Getter Meaning
party_to_charge The leg the report is for, as its number: the one the ApplyCharging named.
time_if_no_tariff_switch The time used, in units of 100 ms, counted from the answer and not from the last report (TS 23.078 clause 4.6.1.2). None after a tariff switch.
time_since_tariff_switch / tariff_switch_interval The two times after a tariff switch, in units of 100 ms.
leg_active / call_active legActive, callActive in CAMEL phases 2 and 3: false means the leg is gone and this is its last figure. True when the member is absent, its default.
call_leg_released_at_tcp_expiry The gsmSSF released the leg because the granted period ran out.

Address

Built with ss7.gt(digits, ssn=…): an SCCP address (E.164, GTI-4). Exposes .digits and .ssn.

Staged components

Invoke and Result are opaque staged components produced by the builders above and consumed by dlg.invoke(...) / dlg.reply(...). You do not construct them directly. An Invoke exposes operation_code and operation_class.

Testing your handlers

You can unit-test a script off the wire, with no peer and no SCTP. siphon.configure rebuilds the process-wide node from a sigtran.yaml (a path, an inline YAML string, or a dict) and returns a Node round-trip handle: it assembles genuine inbound MSUs (real TCAP in a real SCCP UDT) and drives them through the same dialogue engine the live node uses, so your @gsm_map.on_operation(...) handlers run for real. This is the seam the crate's own integration tests drive; a live script never calls it (the binary configures the node, see The node).

node = siphon.configure("sigtran.yaml")   # test-only: build a node to drive

begin = node.assemble_begin(op="mo-forward-sm", called_gt="15550100",
                            called_ssn=8, calling_gt="15550142")
replies = node.deliver(begin, opc=2000, dpc=1000)   # SCCP payloads sent back
assert node.decode(replies[0]).kind == "end"        # the closing End your handler staged
Method Effect
siphon.configure(source) Rebuild the node from a sigtran.yaml (path / YAML string / dict), validating as the Rust loader does (a bad reference raises SigtranError); returns a Node.
node.open_dialogues() Count of currently open TCAP dialogues.
node.metrics() The Prometheus text exposition.
node.assemble_begin(op, called_gt, called_ssn, calling_gt, arg=None, ac=None) Build a genuine inbound Begin(AARQ, Invoke) SCCP payload for op (a kebab-case operation name). Returns the SCCP bytes.
node.assemble_continue(dtid, staged, invoke_id=1, otid=None) Build an inbound Continue for a held-open dialogue keyed to dtid (read off the first reply with decode), carrying a staged Result or Invoke.
node.assemble_tcap(tcap, called_ssn=6) Wrap raw TCAP octets in an inbound SCCP UDT, for what the other helpers cannot build: a damaged message, a Reject, an Abort.
node.deliver(payload, opc=…, dpc=…) Deliver one inbound SCCP payload to the dialogue engine and return the SCCP payloads to send back.
node.sweep(ahead=0.0) Run the dialogue timers as the live node does once a second, with the clock moved ahead seconds forward, and return the SCCP payloads to send.
node.decode(payload) Decode an outbound SCCP payload into a read-only Decoded view: .kind, .otid / .dtid, .app_context, .invoke / .invokes, .result, .result_invoke_id, .error, .rejects (a list of (invoke_id, problem_class, problem_code)), and for an abort .abort_kind, .p_abort_cause, .abort_source.

Hot reload, restated

Routing state lives in Rust, so reloading the script does not drop routes, GTT entries or open dialogues. On reload the script re-registers its termination handlers. Program tables with idempotent calls (address_table(...).add, prepend-on-add_rule) so a reload mid-traffic is safe. See Concepts.

Termination registrations update in place by (SSN, operation), which keeps a reload from dropping in-flight messages. Two consequences: a handler you delete from the script keeps running until overwritten, and moving an operation between a specific on_operation("<name>") and a bare catch-all does not take full effect on a hot reload (the prior registration still wins for that operation). Restart the node (or reconfigure it) to apply either change cleanly.