Struct Client

pub struct Client { /* private fields */ }

Client used to authenticate and interact with Ring.

Implementations

impl Client

pub async fn login( &self, credentials: Credentials, ) -> Result<(), AuthenticationError>

Login to Ring using a set of credentials.

These credentials can either be:

• A username and password (Credentials::User)
• A refresh token (Credentials::RefreshToken)

Example

Login with a Username and Password

use ring_client::Client;

use ring_client::authentication::Credentials;
use ring_client::AuthenticationError;
use ring_client::OperatingSystem;

  let client = Client::new("Home Automation", "mock-system-id", OperatingSystem::Ios);

  let credentials = Credentials::User {
    username: "username".to_string(),
    password: "password".to_string(),
  };

  let attempt = client.login(credentials).await;

  if let Err(AuthenticationError::MfaCodeRequired) = attempt {
    // The user needs to enter a 2FA code.
    client.respond_to_challenge("123456").await.expect("Providing a valid 2FA code should not fail");
  }
  else {
    // The login was successful!
  }

Login with a Refresh Token

If the user has previosuly logged in, Ring will have issued a refresh token. This token can be used on subsequent login attempts to avoid having to complete the full login flow (2FA, etc).

Refresh tokens can be retrieved using Client::get_refresh_token after a successful login.

use ring_client::Client;

use ring_client::authentication::Credentials;
use ring_client::OperatingSystem;

   let client = Client::new("Home Automation", "mock-system-id", OperatingSystem::Ios);

   let refresh_token = Credentials::RefreshToken("".to_string());

   client.login(refresh_token).await.expect("Logging in with a valid refresh token should not fail");

Errors

Returns an error logging in was unsuccessful and a Two Factor Authentication (2FA) challenge was not issued.

pub async fn respond_to_challenge( &self, code: &str, ) -> Result<(), AuthenticationError>

Respond to a challenge issued by Ring during the authentication process.

This is typically used to handle Two Factor Authentication (2FA) challenges

Errors

Returns an error if the challenge could not be completed.

pub async fn get_refresh_token(&self) -> Option<String>

Get the refresh token issued by Ring for the current session.

If Credentials::RefreshToken was used to login initially, this will return the same token.

impl Client

pub async fn get_devices(&self) -> Result<Vec<Device>, ApiError>

Retrieve a list of devices in the Ring account.

Examples

use ring_client::Client;

use ring_client::authentication::Credentials;
use ring_client::OperatingSystem;

let client = Client::new("Home Automation", "mock-system-id", OperatingSystem::Ios);

// For brevity, a Refresh Token is being used here. However, the client can also
// be authenticated using a username and password.
//
// See `Client::login` for more information.
let refresh_token = Credentials::RefreshToken("".to_string());

client.login(refresh_token)
     .await
     .expect("Logging in with a valid refresh token should not fail");

let devices = client.get_devices()
     .await
     .expect("Getting devices not fail");

println!("{:#?}", devices);

Errors

Returns an error if the API request fails. This may occur either as the result of an API error, or if the authentication token needs to be refreshed and it is not successful.

impl Client

pub async fn get_locations(&self) -> Result<Vec<Location<'_>>, ApiError>

Retrieve a list of locations in the Ring account.

Examples

use ring_client::Client;

use ring_client::authentication::Credentials;
use ring_client::OperatingSystem;

let client = Client::new("Home Automation", "mock-system-id", OperatingSystem::Ios);

// For brevity, a Refresh Token is being used here. However, the client can also
// be authenticated using a username and password.
//
// See `Client::login` for more information.
let refresh_token = Credentials::RefreshToken("".to_string());

client.login(refresh_token)
     .await
     .expect("Logging in with a valid refresh token should not fail");

let locations = client.get_locations()
     .await
     .expect("Getting locations should not fail");

let location = locations
     .first()
     .expect("There should be at least one location");

Errors

Returns an error if the API request fails. This may occur either as the result of an API error, or if the authentication token needs to be refreshed and it is not successful.

impl Client

pub fn new( display_name: &str, system_id: &str, operating_system: OperatingSystem, ) -> Self

Create a new client.

The system ID is used by Ring to identify the client on subsequent logins, and should be predictable and consistent per device.

Trait Implementations

impl Debug for Client

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

Formats the value using the given formatter.