Struct QueryBuilder

#[non_exhaustive]
pub struct QueryBuilder<'agent> {
    pub effective_canister_id: Principal,
    pub canister_id: Principal,
    pub method_name: String,
    pub arg: Vec<u8>,
    pub ingress_expiry_datetime: Option<u64>,
    pub use_nonce: bool,
    /* private fields */
}

A Query Request Builder.

This makes it easier to do query calls without actually passing all arguments.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

effective_canister_id: Principal

The effective canister ID of the destination.

canister_id: Principal

The principal ID of the canister being called.

method_name: String

The name of the canister method being called.

arg: Vec<u8>

The argument blob to be passed to the method.

ingress_expiry_datetime: Option<u64>

The Unix timestamp that the request will expire at.

use_nonce: bool

Whether to include a nonce with the message.

Implementations

impl<'agent> QueryBuilder<'agent>

pub fn new( agent: &'agent Agent, canister_id: Principal, method_name: String, ) -> Self

Creates a new query builder with an agent for a particular canister method.

pub fn with_effective_canister_id(self, canister_id: Principal) -> Self

Sets the effective canister ID of the destination.

pub fn with_arg<A: Into<Vec<u8>>>(self, arg: A) -> Self

Sets the argument blob to pass to the canister. For most canisters this should be a Candid-serialized tuple.

pub fn expire_at(self, time: impl Into<OffsetDateTime>) -> Self

Sets ingress_expiry_datetime to the provided timestamp, at nanosecond precision.

pub fn expire_after(self, duration: Duration) -> Self

Sets ingress_expiry_datetime to max(now, 4min).

pub fn with_nonce_generation(self) -> Self

Uses a nonce generated with the agent’s configured nonce factory. By default queries do not use nonces, and thus may get a (briefly) cached response.

pub async fn call(self) -> Result<Vec<u8>, AgentError>

Make a query call. This will return a byte vector.

pub async fn call_with_verification(self) -> Result<Vec<u8>, AgentError>

Make a query call with signature verification. This will return a byte vector.

Compared with call, this method will always verify the signature of the query response regardless the Agent level configuration from AgentBuilder::with_verify_query_signatures.

pub async fn call_without_verification(self) -> Result<Vec<u8>, AgentError>

Make a query call without signature verification. This will return a byte vector.

Compared with call, this method will never verify the signature of the query response regardless the Agent level configuration from AgentBuilder::with_verify_query_signatures.

pub fn sign(self) -> Result<SignedQuery, AgentError>

Sign a query call. This will return a signed::SignedQuery which contains all fields of the query and the signed query in CBOR encoding

Trait Implementations

impl<'agent> Clone for QueryBuilder<'agent>

fn clone(&self) -> QueryBuilder<'agent>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'agent> Debug for QueryBuilder<'agent>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'agent> IntoFuture for QueryBuilder<'agent>

type IntoFuture = Pin<Box<dyn Future<Output = Result<Vec<u8>, AgentError>> + Send + 'agent>>

Which kind of future are we turning this into?

type Output = Result<Vec<u8>, AgentError>

The output that the future will produce on completion.

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.