Attribute Macro update

#[update]

Register an update call entry point.

This attribute macro will export a function with name canister_update <name> in the canister module.

Examples

Basic Usage

#[update]
fn update_function() {
    // ...
}

Custom Export Name

You can customize the name of the exported function.

#[update(name = "some_name")]
fn update_function() {
    // ...
}

Hide From Candid Generation

If you want to hide this method in the Candid generated by export_candid!, you will need to set hidden to true. The entry point still exists in the canister.

#[update(hidden = true)]
fn update_function() {
    // ...
}

Guard Functions

You can specify one or more guard functions to be executed before the update function. Each guard function must return a Result<(), String>. If any guard function returns an error, the update function will not proceed.

fn guard1() -> Result<(), String> {
    // ...
}
fn guard2() -> Result<(), String> {
    // ...
}
#[update(guard = "guard1", guard = "guard2")]
fn update_function() {
    // ...
}

Custom Argument Decoding

You can specify a custom function to decode the arguments. The function must take a Vec<u8> as an argument and return the same type as the update arguments.

fn decode_args(arg_bytes: Vec<u8>) -> (u32, u32) {
   // ...
}
#[update(decode_with = "decode_args")]
fn update_function(a: u32, b: u32) {
   // ...
}

Custom Return Value Encoding

You can specify a custom function to encode the return value. The function must take the update return value as an argument and return a Vec<u8>.

fn encode_result(result: (u32, u32)) -> Vec<u8> {
  // ...
}
#[update(encode_with = "encode_result")]
fn update_function() -> (u32, u32) {
 // ...
}

Manual Reply

The update macro defaults to invoke msg_reply() after the function execution. If you want to execute other code after msg_reply(), you can:

• set manual_reply to true in macro attribute;
• set the return type to PhantomData<T> where T is the return type of the update method;
• call the msg_reply() function explicitly;
• do other stuff;
• return PhantomData;

#[update(manual_reply = true)]
fn update_function() -> PhantomData<MyResult> {
    let result = calculate_result();
    let reply_bytes = candid::encode_one(result).unwrap();
    ic_cdk::api::msg_reply(reply_bytes);
    PhantomData
}