pub struct DocumentChannel { /* private fields */ }Expand description
A live connection to a document’s real-time channel, joined via
crate::ScribeClient::open_document_channel.
Progress on formats that were already converting (or complete) when the
channel was joined arrives as ChannelEvents from Self::next_event
just like anything started with Self::start_conversion after joining.
Heartbeats keep the connection open only while a call on this channel is
waiting, so keep calling Self::next_event during a conversion. The
connection can still be lost, for example to a network failure or a server
restart. A conversion carries on without it: open a new channel on the same
document, and don’t upload it again.
Implementations§
Source§impl DocumentChannel
impl DocumentChannel
Sourcepub async fn start_conversion(
&mut self,
format: OutputFormat,
password: Option<&str>,
) -> Result<String, ScribeError>
pub async fn start_conversion( &mut self, format: OutputFormat, password: Option<&str>, ) -> Result<String, ScribeError>
Starts converting the joined document to format, using its current
settings. If that format is already complete, the server returns its
existing output id instead of starting a new conversion. Returns
immediately with the output id; progress arrives via subsequent
Self::next_event calls.
§Errors
Returns ScribeError::NotFound/ScribeError::Forbidden if the
document doesn’t exist or isn’t owned by the caller,
ScribeError::ConversionInProgress if any non-preview conversion
of the document is running, including that format and the
html_stream that creating the document started (wait for its
ChannelEvent::ConversionComplete, then call this again),
ScribeError::RateLimited if too many conversions were started too
quickly,
ScribeError::NeedsPurchase if the account is out of page
credits, or ScribeError::PasswordRequired if the document is a
protected file and password was None or wrong.
password unlocks a password-protected document. It’s stored
against the document, so later conversions of other formats don’t
need it again. A wrong password isn’t detected here — the server
accepts it, the converter rejects it, and an
ChannelEvent::Error with reason invalid_password arrives from
Self::next_event; retry this call with a corrected password.
Sourcepub async fn next_event(&mut self) -> Result<ChannelEvent, ScribeError>
pub async fn next_event(&mut self) -> Result<ChannelEvent, ScribeError>
§Errors
Returns ScribeError::WebSocket if the connection fails, or
ScribeError::ChannelClosed if it closes before another event
arrives.
Sourcepub async fn close(self) -> Result<(), ScribeError>
pub async fn close(self) -> Result<(), ScribeError>
Closes the connection. One that’s already closed or lost is fine, since that’s what this is for.
§Errors
Returns ScribeError::WebSocket if closing the connection fails with
it still open.