pub struct Canister<'agent, T = ()> { /* private fields */ }
Expand description
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
sourceimpl<'agent, T> Canister<'agent, T>
impl<'agent, T> Canister<'agent, T>
sourcepub fn canister_id_<'canister: 'agent>(&'canister self) -> &Principal
pub fn canister_id_<'canister: 'agent>(&'canister self) -> &Principal
Get the canister ID of this canister.
sourcepub fn interface_<'canister: 'agent>(&'canister self) -> &T
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.
sourcepub fn update_<'canister: 'agent>(
&'canister self,
method_name: &str
) -> AsyncCallBuilder<'agent, 'canister, T>
pub fn update_<'canister: 'agent>(
&'canister self,
method_name: &str
) -> AsyncCallBuilder<'agent, 'canister, T>
Create an AsyncCallBuilder to do an update call.
sourcepub fn query_<'canister: 'agent>(
&'canister self,
method_name: &str
) -> SyncCallBuilder<'agent, 'canister, T>
pub fn query_<'canister: 'agent>(
&'canister self,
method_name: &str
) -> SyncCallBuilder<'agent, 'canister, T>
Create a SyncCallBuilder to do a query call.
sourceimpl<'agent, T> Canister<'agent, T> where
T: Clone,
impl<'agent, T> Canister<'agent, T> where
T: Clone,
sourcepub fn clone_with_(&self, id: Principal) -> Self
pub fn clone_with_(&self, id: Principal) -> Self
Creates a copy of this canister, changing the canister ID to the provided principal.
sourceimpl<'agent> Canister<'agent, ()>
impl<'agent> Canister<'agent, ()>
sourcepub fn builder() -> CanisterBuilder<'agent, ()>
pub fn builder() -> CanisterBuilder<'agent, ()>
Create a CanisterBuilder instance to build a canister abstraction.
sourceimpl<'agent> Canister<'agent, HttpRequestCanister>
impl<'agent> Canister<'agent, HttpRequestCanister>
sourcepub 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<'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,)>
Performs a HTTP request, receiving a HTTP response.
sourcepub fn http_request_update<'canister: 'agent, M: Into<String>, U: Into<String>, B: AsRef<[u8]>>(
&'canister self,
method: M,
url: U,
headers: Vec<HeaderField>,
body: B
) -> impl 'agent + AsyncCall<(HttpResponse,)>
pub fn http_request_update<'canister: 'agent, M: Into<String>, U: Into<String>, B: AsRef<[u8]>>(
&'canister self,
method: M,
url: U,
headers: Vec<HeaderField>,
body: B
) -> impl 'agent + AsyncCall<(HttpResponse,)>
Performs a HTTP request over an update call. Unlike query calls, update calls must pass consensus and therefore cannot be tampered with by a malicious node.
sourcepub fn http_request_stream_callback<'canister: 'agent, M: Into<String>>(
&'canister self,
method: M,
token: Token
) -> impl 'agent + SyncCall<(StreamingCallbackHttpResponse,)>
pub fn http_request_stream_callback<'canister: 'agent, M: Into<String>>(
&'canister self,
method: M,
token: Token
) -> impl 'agent + SyncCall<(StreamingCallbackHttpResponse,)>
Retrieves the next chunk of a stream from a streaming callback, using the method from CallbackStrategy
.
sourceimpl<'agent> Canister<'agent, ManagementCanister>
impl<'agent> Canister<'agent, ManagementCanister>
sourcepub fn canister_status<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<(StatusCallResult,)>
pub fn canister_status<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<(StatusCallResult,)>
Get the status of a canister.
sourcepub fn create_canister<'canister: 'agent>(
&'canister self
) -> CreateCanisterBuilder<'agent, 'canister, ManagementCanister>
pub fn create_canister<'canister: 'agent>(
&'canister self
) -> CreateCanisterBuilder<'agent, 'canister, ManagementCanister>
Create a canister.
sourcepub fn deposit_cycles<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
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.
sourcepub fn delete_canister<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
pub fn delete_canister<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
Deletes a canister.
sourcepub fn provisional_top_up_canister<'canister: 'agent>(
&'canister self,
canister_id: &Principal,
amount: u64
) -> impl 'agent + AsyncCall<()>
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).
sourcepub fn raw_rand<'canister: 'agent>(
&'canister self
) -> impl 'agent + AsyncCall<(Vec<u8>,)>
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.
sourcepub fn start_canister<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
pub fn start_canister<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
Starts a canister.
sourcepub fn stop_canister<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
pub fn stop_canister<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
Stop a canister.
sourcepub fn uninstall_code<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> impl 'agent + AsyncCall<()>
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.
sourcepub fn install_code<'canister: 'agent>(
&'canister self,
canister_id: &Principal,
wasm: &'canister [u8]
) -> InstallCodeBuilder<'agent, 'canister, ManagementCanister>
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.
sourcepub fn update_settings<'canister: 'agent>(
&'canister self,
canister_id: &Principal
) -> UpdateCanisterBuilder<'agent, 'canister, ManagementCanister>
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.)
sourceimpl<'agent> Canister<'agent, Wallet>
impl<'agent> Canister<'agent, Wallet>
sourcepub fn wallet_api_version<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Option<String>,)>
pub fn wallet_api_version<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Option<String>,)>
Get the API version string of the wallet.
sourcepub fn name<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Option<String>,)>
pub fn name<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Option<String>,)>
Get the friendly name of the wallet (if one exists).
sourcepub fn set_name<'canister: 'agent>(
&'canister self,
name: String
) -> impl 'agent + AsyncCall<()>
pub fn set_name<'canister: 'agent>(
&'canister self,
name: String
) -> impl 'agent + AsyncCall<()>
Set the friendly name of the wallet.
sourcepub fn get_controllers<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>
pub fn get_controllers<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>
Get the current controller’s principal ID.
sourcepub fn add_controller<'canister: 'agent>(
&'canister self,
principal: Principal
) -> impl 'agent + AsyncCall<()>
pub fn add_controller<'canister: 'agent>(
&'canister self,
principal: Principal
) -> impl 'agent + AsyncCall<()>
Transfer controller to another principal ID.
sourcepub fn remove_controller<'canister: 'agent>(
&'canister self,
principal: Principal
) -> impl 'agent + AsyncCall<()>
pub fn remove_controller<'canister: 'agent>(
&'canister self,
principal: Principal
) -> impl 'agent + AsyncCall<()>
Remove a user as a wallet controller.
sourcepub fn get_custodians<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>
pub fn get_custodians<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>
Get the list of custodians.
Authorize a new custodian.
Deauthorize a custodian.
sourcepub fn wallet_balance<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(BalanceResult,)>
pub fn wallet_balance<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(BalanceResult,)>
Get the balance.
sourcepub fn wallet_send<'canister: 'agent>(
&'canister self,
destination: &Canister<'agent, Wallet>,
amount: u64
) -> impl 'agent + AsyncCall<(Result<(), String>,)>
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.
sourcepub fn wallet_receive<'canister: 'agent>(
&'canister self
) -> impl 'agent + AsyncCall<((),)>
pub fn wallet_receive<'canister: 'agent>(
&'canister self
) -> impl 'agent + AsyncCall<((),)>
Send cycles to another (hopefully Wallet) canister.
sourcepub fn wallet_create_canister_v1<'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_canister_v1<'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>,)>
Wallet API version 0.1.0 only accepts a single controller
sourcepub fn wallet_create_canister_v2<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>
pub fn wallet_create_canister_v2<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>
Wallet API version >= 0.2.0 accepts multiple controllers
sourcepub async fn wallet_create_canister<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>,
waiter: Delay
) -> Result<CreateResult, AgentError>
pub async fn wallet_create_canister<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>,
waiter: Delay
) -> Result<CreateResult, AgentError>
Call wallet_create_canister_v1 or wallet_create_canister_v2, depending on the cycles wallet version.
sourcepub fn wallet_create_wallet_v1<'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_v1<'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
sourcepub fn wallet_create_wallet_v2<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>
pub fn wallet_create_wallet_v2<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>
Create a wallet canister
sourcepub async fn wallet_create_wallet<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>,
waiter: Delay
) -> Result<CreateResult, AgentError>
pub async fn wallet_create_wallet<'canister: 'agent>(
&'canister self,
cycles: u64,
controllers: Option<Vec<Principal>>,
compute_allocation: Option<ComputeAllocation>,
memory_allocation: Option<MemoryAllocation>,
freezing_threshold: Option<FreezingThreshold>,
waiter: Delay
) -> Result<CreateResult, AgentError>
Call wallet_create_wallet_v1 or wallet_create_wallet_v2, depending on the cycles wallet version.
sourcepub fn wallet_store_wallet_wasm<'canister: 'agent>(
&'canister self,
wasm_module: Vec<u8>
) -> impl 'agent + AsyncCall<()>
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
sourcepub fn add_address<'canister: 'agent>(
&'canister self,
address: AddressEntry
) -> impl 'agent + AsyncCall<()>
pub fn add_address<'canister: 'agent>(
&'canister self,
address: AddressEntry
) -> impl 'agent + AsyncCall<()>
Add a principal to the address book.
sourcepub fn list_addresses<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Vec<AddressEntry>,)>
pub fn list_addresses<'canister: 'agent>(
&'canister self
) -> impl 'agent + SyncCall<(Vec<AddressEntry>,)>
List the entries in the address book.
sourcepub fn remove_address<'canister: 'agent>(
&'canister self,
principal: Principal
) -> impl 'agent + AsyncCall<()>
pub fn remove_address<'canister: 'agent>(
&'canister self,
principal: Principal
) -> impl 'agent + AsyncCall<()>
Remove a principal from the address book.
sourcepub fn get_events<'canister: 'agent>(
&'canister self,
from: Option<u32>,
to: Option<u32>
) -> impl 'agent + SyncCall<(Vec<Event>,)>
pub fn get_events<'canister: 'agent>(
&'canister self,
from: Option<u32>,
to: Option<u32>
) -> impl 'agent + SyncCall<(Vec<Event>,)>
Get a list of all transaction events this wallet remembers.
sourcepub 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,
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.
sourcepub 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,
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.
Trait Implementations
Auto Trait Implementations
impl<'agent, T = ()> !RefUnwindSafe for Canister<'agent, T>
impl<'agent, T> Send for Canister<'agent, T> where
T: Send,
impl<'agent, T> Sync for Canister<'agent, T> where
T: Sync,
impl<'agent, T> Unpin for Canister<'agent, T> where
T: Unpin,
impl<'agent, T = ()> !UnwindSafe for Canister<'agent, T>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more