Struct PluginContext 

pub struct PluginContext<'scope> { /* private fields */ }

Safe capabilities available while the framework calls plugin code.

Logging is valid in every hook. Channel registration is intentionally open only during TelemetryPlugin::initialize; calling a subscription method from another hook returns SdkError::NotNow without touching the SDK.

Implementations

impl<'scope> PluginContext<'scope>

pub const fn game(&self) -> &GameInfo

Metadata copied from the game’s initialization parameters.

pub const fn telemetry_api_version(&self) -> TelemetryApiVersion

Telemetry API version selected by the SCS loader for this session.

This is the negotiated runtime ABI, not the SDK archive version and not the game-specific telemetry schema returned by PluginContext::game. Product code normally relies on TelemetryPlugin::compatibility for mandatory requirements and reads this value only for an explicit optional capability branch.

pub fn log(&self, level: LogLevel, arguments: Arguments<'_>)

Formats and writes one message to the game log.

Interior NUL characters have no representation in a C string. They are replaced with spaces so malformed external text cannot suppress the entire log entry or force application code to handle an FFI detail.

pub fn message(&self, arguments: Arguments<'_>)

Logs an informational message.

pub fn warning(&self, arguments: Arguments<'_>)

Logs a warning message.

pub fn error(&self, arguments: Arguments<'_>)

Logs an error message.

pub fn subscribe_event(&mut self, event: TelemetryEventKind) -> PluginResult

Requests delivery of one telemetry event kind.

Event registration is explicit: the framework never infers it from the presence of TelemetryPlugin::event and does not subscribe to unused frame, configuration, or gameplay callbacks. Registration with SCS is deferred until TelemetryPlugin::initialize returns successfully so the complete set can be rolled back transactionally.

Errors

Returns SdkError::AlreadyRegistered when the same event kind was requested twice, or SdkError::NotNow when called from a callback or shutdown hook instead of initialization. A required event introduced by a newer game schema returns SdkError::Unsupported before foreign registration, independently from its Telemetry API requirement.

pub fn subscribe_event_optional( &mut self, event: TelemetryEventKind, ) -> PluginResult

Requests delivery of an event when the negotiated API and loading game provide it.

An event introduced by a newer API is skipped locally. If SCS reports Unsupported or NotFound while registering it, the remaining required transaction continues. Duplicate declarations, wrong lifecycle phase, and other SDK failures remain errors.

Errors

Returns SdkError::AlreadyRegistered for a duplicate event or SdkError::NotNow outside product initialization. A non-capability SDK registration error later aborts the complete transaction.

pub fn subscribe<T: ChannelValue>( &mut self, channel: Channel<T>, ) -> PluginResult

Subscribes to one scalar channel using its canonical SDK name.

Values are delivered only when they change unless flags includes ChannelFlags::EACH_FRAME. For an indexed channel, use PluginContext::subscribe_at.

Errors

Returns SdkError::InvalidParameter when channel is indexed, SdkError::AlreadyRegistered for a duplicate subscription, or SdkError::NotNow outside initialization. A requested value representation introduced after the negotiated Telemetry API returns SdkError::Unsupported before the SDK registration transaction begins. The same result is returned when the built-in descriptor postdates the loading game’s telemetry schema.

pub fn subscribe_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, flags: ChannelFlags, ) -> PluginResult

Subscribes to one scalar channel with explicit SDK delivery flags.

Errors

Uses the same validation as PluginContext::subscribe.

pub fn subscribe_optional<T: ChannelValue>( &mut self, channel: Channel<T>, ) -> PluginResult

Requests a scalar channel when available in the loading game.

Unlike PluginContext::subscribe, absence of the channel or an unsupported channel-specific conversion does not abort initialization. No callback is delivered for a skipped subscription, so product state must retain an explicit default or unavailable representation.

API- and game-schema-level capability checks are also optional: for example, an i64 request is skipped under Telemetry API 1.00, and a navigation channel is skipped before ETS2 schema 1.12. Invalid descriptor shape, duplicate declarations, and lifecycle misuse remain errors because they indicate a malformed plugin declaration.

Errors

Returns the same descriptor-shape, duplicate, and lifecycle declaration errors as PluginContext::subscribe. Non-capability registration failures still abort the complete transaction.

pub fn subscribe_optional_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, flags: ChannelFlags, ) -> PluginResult

Requests an optional scalar channel with explicit delivery flags.

Errors

Uses the declaration validation documented by PluginContext::subscribe_optional.

pub fn subscribe_at<T: ChannelValue>( &mut self, channel: Channel<T>, index: SdkIndex, ) -> PluginResult

Subscribes to one member of an SDK-indexed channel.

The index selects an element such as one truck wheel. It is independent from the trailer number embedded by PluginContext::subscribe_trailer_at.

Errors

Returns SdkError::InvalidParameter for a scalar descriptor and the normal phase/duplicate errors documented by PluginContext::subscribe.

pub fn subscribe_at_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, index: SdkIndex, flags: ChannelFlags, ) -> PluginResult

Subscribes to an indexed channel with explicit SDK delivery flags.

Errors

Uses the same validation as PluginContext::subscribe_at.

pub fn subscribe_at_optional<T: ChannelValue>( &mut self, channel: Channel<T>, index: SdkIndex, ) -> PluginResult

Requests one indexed channel member when available.

NotFound and UnsupportedType from SCS skip this member without affecting required registrations. Descriptor-shape, duplicate, index, and lifecycle validation remain strict.

Errors

Returns the same declaration errors as PluginContext::subscribe_at. Non-capability registration failures still abort the transaction.

pub fn subscribe_at_optional_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, index: SdkIndex, flags: ChannelFlags, ) -> PluginResult

Requests an optional indexed channel member with delivery flags.

Errors

Uses the declaration validation documented by PluginContext::subscribe_at_optional.

pub fn subscribe_trailer<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, ) -> PluginResult

Subscribes to one scalar channel for an explicit trailer in a chain.

The official static macros use trailer.*, while multi-trailer telemetry is named trailer.0.*, trailer.1.*, and so on. This helper performs that transformation and retains the generated C string for the complete SDK registration lifetime.

Errors

Returns SdkError::InvalidParameter when the descriptor is not a scalar trailer.* channel. TrailerIndex construction already enforces the official 0..10 range. The numbered namespace itself requires ETS2 schema 1.14 or ATS schema 1.01, even when the underlying backward-compatible trailer.* descriptor is older.

pub fn subscribe_trailer_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, flags: ChannelFlags, ) -> PluginResult

Subscribes to a scalar multi-trailer channel with explicit delivery flags.

Errors

Uses the same validation as PluginContext::subscribe_trailer.

pub fn subscribe_trailer_optional<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, ) -> PluginResult

Requests one scalar trailer channel when available.

The trailer name is still validated eagerly; the strong index is valid by construction. Only SCS NotFound and UnsupportedType registration results, or a value representation newer than the negotiated API, are treated as expected absence.

Errors

Returns the same descriptor, duplicate, and lifecycle declaration errors as PluginContext::subscribe_trailer.

pub fn subscribe_trailer_optional_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, flags: ChannelFlags, ) -> PluginResult

Requests an optional scalar trailer channel with delivery flags.

Errors

Uses the declaration validation documented by PluginContext::subscribe_trailer_optional.

pub fn subscribe_trailer_at<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, index: SdkIndex, ) -> PluginResult

Subscribes to one SDK-indexed member of an explicit trailer channel.

For example, trailer index 1 and SDK index 2 select wheel 2 of the second trailer. Both strong index domains are zero-based.

Errors

Returns SdkError::InvalidParameter unless channel is an indexed trailer.* descriptor. The trailer range and scalar sentinel are excluded while constructing TrailerIndex and SdkIndex.

pub fn subscribe_trailer_at_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, index: SdkIndex, flags: ChannelFlags, ) -> PluginResult

Subscribes to an indexed multi-trailer channel with delivery flags.

Errors

Uses the same validation as PluginContext::subscribe_trailer_at.

pub fn subscribe_trailer_at_optional<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, index: SdkIndex, ) -> PluginResult

Requests an indexed member of one trailer channel when available.

Both index domains remain explicit and strictly validated. Expected SDK capability absence skips only this declaration.

Errors

Returns the same descriptor, index, duplicate, and lifecycle declaration errors as PluginContext::subscribe_trailer_at.

pub fn subscribe_trailer_at_optional_with_flags<T: ChannelValue>( &mut self, channel: Channel<T>, trailer_index: TrailerIndex, index: SdkIndex, flags: ChannelFlags, ) -> PluginResult

Requests an optional indexed trailer channel with delivery flags.

Errors

Uses the declaration validation documented by PluginContext::subscribe_trailer_at_optional.