Struct ic_utils::canister::Canister

pub struct Canister<'agent, T = ()> { /* fields omitted */ }

Create an encapsulation of a Canister running on the Internet Computer. This supports making calls to methods, installing code if needed, and various utilities related to a canister.

This is the higher level construct for talking to a canister on the Internet Computer.

Implementations

impl<'agent, T> Canister<'agent, T>

pub fn canister_id_<'canister: 'agent>(&'canister self) -> &Principal

Get the canister ID of this canister.

pub fn interface_<'canister: 'agent>(&'canister self) -> &T

Get the interface object from this canister. Sometimes those interfaces might have custom methods that are useful.

pub fn update_<'canister: 'agent>(
    &'canister self,
    method_name: &str
) -> AsyncCallBuilder<'agent, 'canister, T>

Create an AsyncCallBuilder to do an update call.

pub fn query_<'canister: 'agent>(
    &'canister self,
    method_name: &str
) -> SyncCallBuilder<'agent, 'canister, T>

Create a SyncCallBuilder to do a query call.

impl<'agent, T> Canister<'agent, T> where
    T: Clone, 

pub fn clone_with_(&self, id: Principal) -> Self

impl<'agent> Canister<'agent, ()>

pub fn builder() -> CanisterBuilder<'agent, ()>

Create a CanisterBuilder instance to build a canister abstraction.

impl<'agent> Canister<'agent, HttpRequestCanister>

pub fn http_request<'canister: 'agent, M: Into<String>, U: Into<String>, B: AsRef<[u8]>>(
    &'canister self,
    method: M,
    url: U,
    headers: Vec<HeaderField>,
    body: B
) -> impl 'agent + SyncCall<(HttpResponse,)>

pub fn http_request_stream_callback<'canister: 'agent, M: Into<String>>(
    &'canister self,
    method: M,
    token: Token
) -> impl 'agent + SyncCall<(StreamingCallbackHttpResponse,)>

impl<'agent> Canister<'agent, ManagementCanister>

pub fn canister_status<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<(StatusCallResult,)>

Get the status of a canister.

pub fn create_canister<'canister: 'agent>(
    &'canister self
) -> CreateCanisterBuilder<'agent, 'canister, ManagementCanister>

Create a canister.

pub fn deposit_cycles<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

This method deposits the cycles included in this call into the specified canister. Only the controller of the canister can deposit cycles.

pub fn delete_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

Deletes a canister.

pub fn provisional_top_up_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal,
    amount: u64
) -> impl 'agent + AsyncCall<()>

Until developers can convert real ICP tokens to a top up an existing canister, the system provides the provisional_top_up_canister method. It adds amount cycles to the balance of canister identified by amount (implicitly capping it at MAX_CANISTER_BALANCE).

pub fn raw_rand<'canister: 'agent>(
    &'canister self
) -> impl 'agent + AsyncCall<(Vec<u8>,)>

This method takes no input and returns 32 pseudo-random bytes to the caller. The return value is unknown to any part of the IC at time of the submission of this call. A new return value is generated for each call to this method.

pub fn start_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

Starts a canister.

pub fn stop_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

Stop a canister.

pub fn uninstall_code<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

This method removes a canister’s code and state, making the canister empty again. Only the controller of the canister can uninstall code. Uninstalling a canister’s code will reject all calls that the canister has not yet responded to, and drop the canister’s code and state. Outstanding responses to the canister will not be processed, even if they arrive after code has been installed again. The canister is now empty. In particular, any incoming or queued calls will be rejected.

pub fn install_code<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal,
    wasm: &'canister [u8]
) -> InstallCodeBuilder<'agent, 'canister, ManagementCanister>

Install a canister, with all the arguments necessary for creating the canister.

pub fn update_settings<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> UpdateCanisterBuilder<'agent, 'canister, ManagementCanister>

Update one or more of a canisters settings (i.e its controller, compute allocation, or memory allocation.)

impl<'agent> Canister<'agent, Wallet>

pub fn name<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Option<String>,)>

pub fn set_name<'canister: 'agent>(
    &'canister self,
    name: String
) -> impl 'agent + AsyncCall<()>

pub fn get_controllers<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>

Get the current controller’s principal ID.

pub fn add_controller<'canister: 'agent>(
    &'canister self,
    principal: Principal
) -> impl 'agent + AsyncCall<()>

Transfer controller to another principal ID.

pub fn remove_controller<'canister: 'agent>(
    &'canister self,
    principal: Principal
) -> impl 'agent + AsyncCall<()>

pub fn get_custodians<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>

Get the list of custodians.

pub fn authorize<'canister: 'agent>(
    &'canister self,
    custodian: Principal
) -> impl 'agent + AsyncCall<()>

Authorize a new custodian.

pub fn deauthorize<'canister: 'agent>(
    &'canister self,
    custodian: Principal
) -> impl 'agent + AsyncCall<()>

Deauthorize a custodian.

pub fn wallet_balance<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(BalanceResult,)>

Get the balance.

pub fn wallet_send<'canister: 'agent>(
    &'canister self,
    destination: &Canister<'agent, Wallet>,
    amount: u64
) -> impl 'agent + AsyncCall<(Result<(), String>,)>

Send cycles to another (hopefully Wallet) canister.

pub fn wallet_receive<'canister: 'agent>(
    &'canister self
) -> impl 'agent + AsyncCall<((),)>

Send cycles to another (hopefully Wallet) canister.

pub fn wallet_create_canister<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controller: Option<Principal>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

pub fn wallet_create_wallet<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controller: Option<Principal>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a wallet canister

pub fn wallet_store_wallet_wasm<'canister: 'agent>(
    &'canister self,
    wasm_module: Vec<u8>
) -> impl 'agent + AsyncCall<()>

Store the wallet WASM inside the wallet canister. This is needed to enable wallet_create_wallet

pub fn add_address<'canister: 'agent>(
    &'canister self,
    address: AddressEntry
) -> impl 'agent + AsyncCall<()>

pub fn list_addresses<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Vec<AddressEntry>,)>

pub fn remove_address<'canister: 'agent>(
    &'canister self,
    principal: Principal
) -> impl 'agent + AsyncCall<()>

pub fn get_events<'canister: 'agent>(
    &'canister self,
    from: Option<u32>,
    to: Option<u32>
) -> impl 'agent + SyncCall<(Vec<Event>,)>

pub fn call<'canister: 'agent, Out, M: Into<String>>(
    &'canister self,
    destination: &'canister Canister<'canister>,
    method_name: M,
    arg: Argument,
    amount: u64
) -> CallForwarder<'agent, 'canister, Out> where
    Out: for<'de> ArgumentDecoder<'de> + Send + Sync, 

Forward a call to another canister, including an amount of cycles from the wallet.

pub fn call_forward<'canister: 'agent, Out: 'agent>(
    &'canister self,
    call: AsyncCaller<'agent, Out>,
    amount: u64
) -> Result<impl 'agent + AsyncCall<Out>, AgentError> where
    Out: for<'de> ArgumentDecoder<'de> + Send + Sync, 

Forward a call using another call’s builder. This takes an UpdateBuilder, marshalls it to a buffer, and sends it through the wallet canister, adding a separate amount.