Handle Binary Payloads

The Internet Computer also allows developers to send and receive binary data like JPG or PNG images.

A fully functional example of how to use IC4J API to call a Canister method with binary payload can be found here.

This is an example to use Motoko to call the canister. canister code

The canister will receive a binary payload in add function and stores it. The Function get then returns the stored payload.

The Binary payload type is an array of Nat8.

main.mo

actor {
  let images = Map.HashMap<Text, Blob>(0, Text.equal, Text.hash);
  
  public func add(name : Text, image : [Nat8]) : async Text {
    let blob : Blob = Blob.fromArray(image);
    Debug.print("Source Image Size " #debug_show(blob.size()));
    images.put(name, blob );
    return  name;
  };

  public query func get(name : Text) : async [Nat8] {
    let blob : ?Blob = images.get(name);
    switch blob {
            case (null) { return [] };
            case (?image) { 
              Debug.print("Result Image Size " #debug_show(image.size()));
              Blob.toArray(image);
               };
        };  
  };
};

In Java the proxy interface ImageProxy is created with the 2 methods get and add.

ImagesProxy.java

public interface ImagesProxy {	
	@QUERY
	@Name("get")
	public byte[] get(@Argument(Type.TEXT)String name );	
	
	@UPDATE
	@Name("add")
	@Waiter(timeout = 30)
	public CompletableFuture<String> add(@Argument(Type.TEXT)String name, @Argument(Type.NAT8)byte[] image);
}

Then in a simple Java class , ProxyBuilder can be used to create Canister Java proxy.

The source can be found in Main.java file.

Main.java

byte[] image = getImage(IMAGE_FILE, "png");
		
String name  = IMAGE_FILE;
ImagesProxy images = ProxyBuilder.create(agent, Principal.fromString(icCanister))
				.getProxy(ImagesProxy.class);		
CompletableFuture<String> proxyResponse = images.add(name, image);

String output = proxyResponse.get();		
byte[] imageResult = images.get(name);	

Binary Candid payload ([Nat8]) can be represented in Java either as byte[] array or Byte[] array.