Module event 

A call’s event stream (story C-3, the app-sdk epic’s keystone).

Today a Call is only visible by calling methods on it at the right moment — is_on_hold, transfer, is_ended — which means a host has to know when to look. This module is the alternative: every state change a call goes through is also pushed, once, as a CallEvent, onto a channel the call owns and hands out exactly one receiver for (CallEvents).

The vocabulary here is deliberately close to docs/specs/app-contract.md §5’s wire events — that spec is what this enum exists to make buildable — but this module has no wire format and no serialization; that stays out of sipx-call entirely and lives in the (future) sipx-app-protocol crate (C-5). See also docs/designs/app-sdk.md.

Every variant here is emitted by this crate except one, and that one is deliberate:

• EndCause::Rejected has no producer at this layer for a structural reason rather than a sequencing one. A Call does not exist until an INVITE has already succeeded (2xx and ACK), so by the time there is a call to end, refusing it is no longer possible — what ends an answered call is a BYE. Refusing happens before a Call is built. It is kept in the enum because the app-visible call of C-4/app-host exists from the incoming INVITE onward and will produce it, and because adding a variant after the fact is exactly the kind of wire-breaking change §4 of the contract spec warns about.

One stream here is not a call’s: Invitation hands out a CallEvents too, and its only event is Ended(EndCause::RemoteCancel) — an invitation that was withdrawn before it could become a call (S-23, RFC 3261 §9.2). It is the same type deliberately. A host that is ringing and a host that is talking both need to be told the thing ended and why, and giving the pre-answer half a channel of its own would mean two vocabularies for one question.

PlaybackFinished and RecordingFinished are emitted by Call::play and Call::record_until_idle. M-17 added the control half of playback — a queue, stopping, interrupting on a digit — and reports completion through the same variant rather than a new one, naming the playback it is about.

Structs

CallEvents

A call’s event stream: one receiver, bounded, owned by whoever calls Call::events first.

Enums

CallEvent

Something that happened to a call, in the order it happened.

EndCause

Why a call ended.