FritzApi.Client (fritz_api v3.1.0)

A FritzApi API Client

Summary

Functions

execute_command(client, cmd, params \\ [])

Runs a home automation command and returns its decoded response body.

Authenticate with the FritzApi API using the name and password of the user.

new(opts \\ [])

Creates a new FritzApi API client.

session_id(client)

Returns the session ID of a logged in client, or nil.

Types

t()

@type t() :: %FritzApi.Client{
  base_url: String.t(),
  http_client: module(),
  request_opts: Keyword.t(),
  session_id: String.t() | nil
}

A client, as returned by new/1.

Treat the struct as private: build it with new/1 and read the session ID with session_id/1 rather than matching on the fields, which may change.

Functions

execute_command(client, cmd, params \\ [])

@spec execute_command(t(), String.t(), Keyword.t()) ::
  {:ok, term()} | {:error, FritzApi.Error.t()}

Runs a home automation command and returns its decoded response body.

FritzApi wraps the commonly used commands, but the FritzBox supports more than are wrapped here. Use this to reach the rest; see the AVM Home Automation documentation for the available commands and their parameters.

Examples

iex> FritzApi.Client.execute_command(client, "setsimpleonoff", ain: ain, onoff: 2)
{:ok, "1"}

login(client, username, password)

@spec login(t(), FritzApi.username(), FritzApi.password()) ::
  {:ok, t()} | {:error, FritzApi.Error.t()}

Authenticate with the FritzApi API using the name and password of the user.

A valid session ID is required in order to interact with the FritzBox API.

Each application should only acquire a single session ID since the number of sessions to a FritzBox is limited.

In principle, each session ID has a validity of 60 Minutes whereby the validity period gets extended with every access to the API. However, if any application tries to access the API with an invalid session ID, all other sessions get terminated.

iex> {:ok, client} = FritzApi.Client.new()
...>                 |> FritzApi.Client.login(username, password)
{:ok, %FritzApi.Client{}}

new(opts \\ [])

@spec new(Keyword.t()) :: t()

Creates a new FritzApi API client.

Options

:base_url - the base URL for all endpoints (default: http://fritz.box)
:http_client - a module implementing the FritzApi.HTTPClient behaviour (default: the :client application environment value). Note that only the configured :client gets a connection pool started for it at boot.
:request_opts - options passed to FritzApi.HTTPClient.get/2 (default: the :client_request_opts application environment value)
:session_id - an existing session ID, to reuse a session across restarts

Examples

iex> client = FritzApi.Client.new()
%FritzApi.Client{}

session_id(client)

@spec session_id(t()) :: String.t() | nil

Returns the session ID of a logged in client, or nil.