Struct grammers_mtproto::Mtp

pub struct Mtp { /* fields omitted */ }

An implementation of the Mobile Transport Protocol for ciphertext (encrypted) messages.

When working with unencrypted data (for example, when generating a new authorization key), the serialize_plain_message may be used to wrap a serialized request inside a message.

When working with encrypted data (every other time besides generating authorization keys), use enqueue_request with the serialized request that you want to send. You may enqueue as many requests as you want.

Once your transport is ready to send more data, use serialize_encrypted_messages to pop requests from the queue, serialize them, and encrypt them. This data can be sent to the server.

Once your transport receives some data, use process_encrypted_response to decrypt, deserialize and process the server's response. This response may contain replies to your previously-sent requests.

Finally, poll_response can be used to poll for server's responses to your previously-sent requests.

When server responses

Implementations

impl Mtp

pub fn new(auth_key: AuthKey) -> Self

Creates a new instance with default settings.

pub fn build() -> MtpBuilder

Returns a builder to configure certain parameters.

pub fn enqueue_request(&mut self, body: Vec<u8>) -> MsgId

Enqueues a request and returns its associated msg_id.

Once a response arrives and it is decrypted, the caller is expected to compare the msg_id against the msg_id of previously enqueued requests to determine to which of these the response belongs.

If a certain amount of time passes and the enqueued request has not been sent yet, the message ID will become stale and Telegram will reject it. The caller is then expected to re-enqueue their request and send a new encrypted message.

Panics

The method panics if the body length is not padded to 4 bytes. The serialization of requests will always be correctly padded, so adding an error case for this rare case (impossible with the expected inputs) would simply be unnecessary.

The method also panics if the body length is too large for similar reasons. It is not reasonable to construct huge requests (although possible) because they would likely fail with a RPC error anyway, so we avoid another error case by simply panicking.

The definition of "too large" is roughly 1MB, so as long as the payload is below that mark, it's safe to call.

pub fn serialize_encrypted_messages(&mut self) -> Option<Vec<u8>>

If there is one or more requests enqueued, this method will pack as many as possible into a single message, serialize it, and return it encrypted using the current authorization key as indicated by the MTProto 2.0 guidelines.

If there are no enqueued requests, the method returns None.

pub fn process_encrypted_response(
    &mut self,
    ciphertext: &[u8]
) -> Result<(), DeserializeError>

Processes an encrypted response from the server. If the response contains replies to previously-sent requests, they will be enqueued, and can be polled for later with poll_response.

pub fn poll_response(
    &mut self
) -> Option<(MsgId, Result<Vec<u8>, RequestError>)>

Poll for responses to previously-sent Remote Procedure Calls.

If there are no new server responses, the method returns None.

pub fn poll_update(&mut self) -> Option<Vec<u8>>

Poll for updates that arrived.

If there are no new updates, the method returns None.