Struct sn_client::ClientRegister

pub struct ClientRegister { /* private fields */ }

Cached operations made to an offline Register instance are applied locally only, and accumulated until the user explicitly calls ‘sync’. The user can switch back to sync with the network for every op by invoking online API.

Implementations

impl ClientRegister

pub fn create(client: Client, meta: XorName) -> Self

Create a new Register Locally.

Arguments

• ‘client’ - Client
• ‘meta’ - XorName

Example

let client = Client::new(SecretKey::random(), None, None, None).await?;
let address = XorName::random(&mut rng);
// Here we create a ClientRegister
let register = ClientRegister::create(client.clone(), address);

pub fn create_with_addr(client: Client, addr: RegisterAddress) -> Self

Create a new Register locally with a specific address.

Arguments

• ‘client’ - Client
• ‘addr’ - RegisterAddress

Example

let client = Client::new(SecretKey::random(), None, None, None).await?;
let address = RegisterAddress::new(XorName::random(&mut rng), client.signer_pk());
// Here we create a ClientRegister
let register = ClientRegister::create_with_addr(client.clone(), address);

pub async fn create_online( client: Client, meta: XorName, wallet_client: &mut WalletClient, verify_store: bool, perms: Permissions ) -> Result<(Self, NanoTokens, NanoTokens), Error>

Create a new Register and send it to the Network.

Arguments

• ‘client’ - Client
• ‘meta’ - XorName
• ‘wallet_client’ - A borrowed mutable WalletClient
• verify_store - A boolean to verify store. Set this to true for mandatory verification.
• ‘perms’ - Permissions

Return type: Result<(Self, NanoTokens, NanoTokens)>

Example

let client = Client::new(SecretKey::random(), None, None, None).await?;
let address = XorName::random(&mut rng);
let mut wallet_client = WalletClient::new(client.clone(), wallet);
let permissions = Permissions::default();
// Instantiate a new Register replica from a predefined address.
// The create_online function runs a [sync](ClientRegister::sync) internally.
let (client_register, mut total_cost, mut total_royalties) = ClientRegister::create_online(
        client,
        address,
        &mut wallet_client,
        false,
        permissions,
    ).await?;

pub fn address(&self) -> &RegisterAddress

Return type: RegisterAddress

Example

// Instantiate a ClientRegister (i.e. with create_online)
let (client_register, mut cost, mut royalties) = ClientRegister::create_online//(...)
// From there we can use the address. In this example, we print it out:
println!("REGISTER_ADDRESS={}", client_register.address().to_hex());

pub fn owner(&self) -> PublicKey

Returns the Owner of the Register.

Return type: PublicKey

Example

// Instantiate a ClientRegister (i.e. with create_online)
let (client_register, mut cost, mut royalties) = ClientRegister::create_online//(...)
// From there we can use the owner. In this example, we print it out:
println!("REGISTER_OWNER={}", client_register.owner().to_hex());

pub fn permissions(&self) -> &Permissions

Returns the Permissions of the Register.

Return type: Permissions

Example

let mut wallet_client = WalletClient::new(client.clone(), wallet);
let permissions = Permissions::default();
// Instantiate a ClientRegister (i.e. with create_online)
let (client_register, mut cost, mut royalties) = ClientRegister::create_online//(...)
// From there we can use the permissions. In this example, we print it out:
let permissions = client_register.permissions();
println!("REGISTER_PERMS={:?}",permissions);

pub fn size(&self) -> u64

Return the number of items held in the register.

Return type: u64

Example

// Instantiate a ClientRegister (i.e. with create_online)
let (client_register, mut cost, mut royalties) = ClientRegister::create_online//(...)
// From there we can see the size. In this example, we print it out:
println!("REGISTER_SIZE={}", client_register.size());

pub fn get(&self, hash: EntryHash) -> Result<&Entry, Error>

Return a value corresponding to the provided ‘hash’, if present.

pub fn read(&self) -> BTreeSet<(EntryHash, Entry)>

Read the last entry, or entries when there are branches, if the register is not empty.

Return type: BTreeSet<(EntryHash, Entry)>

Example

let client = Client::new(SecretKey::random(), None, None, None).await?;
let address = XorName::random(&mut rng);
// Read as bytes into the ClientRegister instance
let register = ClientRegister::create(client.clone(), address).read();

pub fn write(&mut self, entry: &[u8]) -> Result<EntryHash, Error>

Write a new value onto the Register atop latest value. It returns an error if it finds branches in the content/entries; if it is required to merge/resolve the branches, invoke the write_merging_branches API.

Arguments

• ‘entry’ - u8 (i.e .as_bytes)

Example

let client = Client::new(SecretKey::random(), None, None, None).await?;
let address = XorName::random(&mut rng);
let entry = "Register entry";
// Write as bytes into the ClientRegister instance
let mut register = ClientRegister::create(client.clone(), address).write(entry.as_bytes());

pub fn write_merging_branches( &mut self, entry: &[u8] ) -> Result<EntryHash, Error>

Write a new value onto the Register atop of the latest value. If there are any branches of content or entries, it automatically merges them. Leaving the new value as a single latest value on the Register. Note you can use the write API if you need to handle content/entries branches in a different way.

Arguments

• ‘entry’ - u8 (i.e .as_bytes)

Example

let client = Client::new(SecretKey::random(), None, None, None).await?;
let address = XorName::random(&mut rng);
let entry = "entry_input_here";
let mut mutable_register = ClientRegister::create(client.clone(), address);
let message = "Register entry";
let register = mutable_register.write_merging_branches(message.as_bytes());

pub fn write_atop( &mut self, entry: &[u8], children: &BTreeSet<EntryHash> ) -> Result<EntryHash, Error>

Write a new value onto the Register atop the set of branches/entries referenced by the provided list of their corresponding entry hash. Note you can use write_merging_branches API instead if you want to write atop all exiting branches/entries.

Arguments

• ‘entry’ - u8 (i.e .as_bytes)
• ‘children’ - BTreeSet<EntryHash>

Example

let mut rng = rand::thread_rng();
let client = Client::new(SecretKey::random(), None, None, None).await?;
let address = XorName::random(&mut rng);
let mut mutable_register = ClientRegister::create(client.clone(), address);
let meta = "Register entry".as_bytes();
let register = mutable_register.write_atop(meta, &BTreeSet::default());

pub async fn sync( &mut self, wallet_client: &mut WalletClient, verify_store: bool, payment_info: Option<(Payment, PeerId)> ) -> Result<(NanoTokens, NanoTokens), Error>

Sync this Register with the replicas on the network. This will optionally verify the stored Register on the network is the same as the local one. If payment info is provided it won’t try to make the payment.

Arguments

• ‘wallet_client’ - WalletClient
• ‘verify_store’ - Boolean

Return type: Result<(NanoTokens, NanoTokens)>

Example

let address = XorName::random(&mut rng);
let client = Client::new(SecretKey::random(), None, None, None).await?;
let mut wallet_client = WalletClient::new(client.clone(), wallet);
// Run sync of a Client Register instance
let mut register =
            ClientRegister::create(client, address).sync(&mut wallet_client, true, None).await?;

pub async fn push(&mut self, verify_store: bool) -> Result<(), Error>

Push all operations made locally to the replicas of this Register on the network. This optionally verifies that the stored Register is the same as our local register.

Arguments

• ‘verify_store’ - Boolean

Example

let address = XorName::random(&mut rng);
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Pass the boolean value to the Client Register instance via .Push()
let mut binding = ClientRegister::create(client, address);
let register = binding.push(false);

pub async fn write_online( &mut self, entry: &[u8], verify_store: bool ) -> Result<(), Error>

Write a new value onto the Register atop of the latest value. It returns an error if it finds branches in the content / entries. If so, then it’s required to merge or resolve the branches. In that case, invoke the write_merging_branches API.

Arguments

• ‘entry’ - u8 (i.e .as_bytes)
• ‘verify_store’ - Boolean

Example

let address = XorName::random(&mut rng);
let client = Client::new(SecretKey::random(), None, None, None).await?;
let meta = "Register entry".as_bytes();
// Use of the 'write_online' example:
let mut binding = ClientRegister::create(client, address);
let register = binding.write_online(meta,false);

pub async fn write_merging_branches_online( &mut self, entry: &[u8], verify_store: bool ) -> Result<(), Error>

Write a new value onto the Register atop of the latest value. If there are branches of content/entries, it will automatically merge them. This will leave a single new value as the latest entry into the Register. Note that you can use the write API if you need to handle content/entries branches in a different way.

Arguments

• ‘entry’ - u8 (i.e .as_bytes)
• ‘verify_store’ - Boolean

Example

let address = XorName::random(&mut rng);
let client = Client::new(SecretKey::random(), None, None, None).await?;
let meta = "Entry".as_bytes();
// Use of the 'write_merging_branches_online':
let mut binding = ClientRegister::create(client, address);
let register = binding.write_merging_branches_online(meta,false);

pub async fn write_atop_online( &mut self, entry: &[u8], children: &BTreeSet<EntryHash>, verify_store: bool ) -> Result<(), Error>

Write a new value onto the Register atop the set of branches/entries referenced by the provided list to their corresponding entry hash. Note you can use write_merging_branches API if you want to write atop of all exiting branches/entries instead.

Arguments

• ‘entry’ - u8 (i.e .as_bytes)
• ‘children’ - BTreeSet<EntryHash>
• ‘verify_store’ - Boolean

Return type:

Example

let mut rng = rand::thread_rng();
let address = XorName::random(&mut rng);
let client = Client::new(SecretKey::random(), None, None, None).await?;
let entry = "Entry".as_bytes();
let tree_set = BTreeSet::new();
// Use of the 'write_atop_online':
let mut binding = ClientRegister::create(client, address);
let mut register = binding.write_atop_online(entry,&tree_set,false);

pub fn merkle_reg(&self) -> &MerkleReg<Entry>

Access the underlying MerkleReg (e.g. for access to history) NOTE: This API is unstable and may be removed in the future

Trait Implementations

impl Clone for ClientRegister

fn clone(&self) -> ClientRegister

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ClientRegister

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

Formats the value using the given formatter.