Struct ic_kit::prelude::CallBuilder

pub struct CallBuilder { /* private fields */ }

A call builder that let’s you create an inter-canister call which can be then sent to the destination.

Implementations

impl CallBuilder

pub fn new<S: Into<String>>(canister_id: Principal, method_name: S) -> Self

Create a new call constructor, calling this method does nothing unless one of the perform methods are called.

pub fn with_args<T: ArgumentEncoder>(self, arguments: T) -> Self

Use the given candid tuple value as the argument.

Panics

This method panics if the argument for this call is already set via a prior call to any of the with_args, with_arg or with_arg_raw.

Use clear_args if you want to reset the arguments.

pub fn with_arg<T: CandidType>(self, argument: T) -> Self

Shorthand for with_args((argument, )).

Panics

This method panics if the argument for this call is already set via a prior call to any of the with_args, with_arg or with_arg_raw.

Use clear_args if you want to reset the arguments.

pub fn with_arg_raw<A: Into<Vec<u8>>>(self, argument: A) -> Self

Set the raw argument that can be used for this call, this does not use candid to serialize the call argument and uses the provided raw buffer as the argument.

Be sure that you know what you’re doing when using this method.

Panics

This method panics if the argument for this call is already set via a prior call to any of the with_args, with_arg or with_arg_raw.

Use clear_args if you want to reset the arguments.

pub fn clear_args(&mut self)

Clear any arguments set for this call. After calling this method you can call with_arg* methods again without the panic.

pub fn with_payment(self, payment: Cycles) -> Self

Set the payment amount for the canister. This will overwrite any previously added cycles to this call, use add_payment if you want to increment the amount of used cycles in this call.

Safety

Be sure that your canister has the provided amount of cycles upon performing the call, since any of the perform methods will just trap the canister if the provided payment amount is larger than the amount of canister’s balance.

pub fn add_payment(self, payment: Cycles) -> Self

Add the given provided amount of cycles to the cycles already provided to this call.

pub fn perform_one_way(self)

Perform a call when you do not care about the response in anyway. We advise you to use this method when you can since it is probably cheaper.

Traps

This method traps if the amount determined in the payment is larger than the canister’s balance at the time of invocation.

pub async fn perform_rejection(&self) -> Result<(), CallError>

Use this method when you want to perform a call and only care about the delivery status of the call and don’t need the returned buffer in anyway.

Traps

This method traps if the amount determined in the payment is larger than the canister’s balance at the time of invocation.

pub async fn perform_raw(&self) -> Result<Vec<u8>, CallError>

Perform the call and return the raw response buffer without decoding it.

Traps

This method traps if the amount determined in the payment is larger than the canister’s balance at the time of invocation.

pub async fn perform<R: for<'a> ArgumentDecoder<'a>>(
    &self
) -> Result<R, CallError>

Perform the call and return a future which will resolve to the candid decoded response. Or any of the errors that might happen, consider looking at other alternatives of this method as well if you don’t care about the response or want the raw/non-decoded response.

Traps

This method traps if the amount determined in the payment is larger than the canister’s balance at the time of invocation.

pub async fn perform_one<T>(&self) -> Result<T, CallError> where
    T: DeserializeOwned + CandidType, 

Perform the call and return a future which will resolve to the candid decoded response. Unlink perform, this method only expects a result with one argument from the canister, and decodes the arguments using the candid’s decode_one.

Traps

This method traps if the amount determined in the payment is larger than the canister’s balance at the time of invocation.