Introduction

Bbox API router client is a Kotlin HTTP client library for accessing Bbox Router API. Those API are available on http://bbox.lan if you have a Bbox which is the home gateway provided by French Internet Service Provider Bouygues Telecom.

This library is fully compatible with Kotlin, Java & Android projects.

Overview

This call requires authentication :

val bboxapi = BboxApiRouter()
bboxapi.setPassword("root")

bboxapi.getVoipInfo { _, response, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            when {
                ex.exception is UnknownHostException -> println("hostname bbox.lan was not found")
                ex.exception is HttpException -> println("http error : ${response.statusCode}")
                else -> ex.printStackTrace()
            }
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

BboxApi bboxapi = new BboxApiRouter();
bboxapi.setPassword("root");

bboxapi.getVoipInfo(new Handler<List<Voip>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        if (error.getException() instanceof UnknownHostException) {
            System.out.println("hostname bbox.lan was not found");
        } else if (error.getException() instanceof HttpException) {
            System.out.println("http error : " + response.getStatusCode());
        } else {
            error.printStackTrace();
        }
    }

    @Override
    public void success(Request request, Response response, List<Voip> data) {
        System.out.println(data);
    }
});

Replace "root" with your Bbox admin interface password

Most of the APIs require authentication via setPassword(password: String) which is Bbox admin interface password.

method	API call	require basic auth	description
login	POST /login	false	login
logout	POST /logout	true	logout
getSummary	GET /summary	false	information summary
getVoipInfo	GET /voip	true	voip data
getDeviceInfo	GET /device	false(*)	device information
getCallLogs	GET /voip/fullcalllog/$line	true	call log
getHosts	GET /hosts	false(*)	known hosts
getWirelessInfo	GET /wireless	true	wireless info
setWifiState	PUT /wireless?radio.enable=1	true	set wifi state
setDisplayState	PUT /device/display?luminosity=100	true	set display state
voipDial	PUT /voip/dial?line=$line&number=$num	true	dial phone number
reboot	POST /device/reboot?btoken=xxx	true	reboot bbox
getXdslInfo	GET /wan/xdsl	false	get xdsl information
getWanIpInfo	GET /wan/ip	false	get wan ip info
setWifiMacFilter	PUT /wireless/acl	true	enable/disable wifi mac filter
getWifiMacFilter	GET /wireless/acl	true	get wifi mac filters
createMacFilterRule	POST /wireless/acl?btoken=xxx	true	create wifi mac filter
updateMacFilterRule	PUT /wireless/acl/$rule	true	update wifi mac filter
deleteMacFilterRule	DELETE /wireless/acl/$rule	true	delete wifi mac filter
startPasswordRecovery	POST /password-recovery	false	start password recovery process
verifyPasswordRecovery	GET /password-recovery/verify	false	check if push button has been pressed
resetPassword	POST /reset-password?btoken=$btoken	true	reset the password
getToken	POST /oauth/token	false	get Oauth2.0 access token / refresh token
refreshToken	POST /oauth/token	false	refresh an Oauth2.0 access token

(*) some information may be missing when unauthenticated

Usage

Gradle

Dependency is available on JCenter or Maven Central with Gradle, from JCenter or MavenCentral :

repositories {
    jcenter() //or mavenCentral()
}

dependencies {
    compile 'fr.bmartel:bboxapi-router:2.1.6' //for JVM
    compile 'fr.bmartel:bboxapi-router-android:2.1.6' //for Android
}

Synchronous & Asynchronous

All methods have an asynchronous & synchronous version. The synchronous version is suffixed with Sync :

• getSummary is asynchronous, result is returned in callback function
• getSummarySync is synchronous, it directly returns the result

Format

The format is the same as the one used in Fuel HTTP client library

• Asynchronous method

The callback function is given in parameter, a Request & Response objects are returned along with a Result object holding the data and a FuelError object in case of failure.

For instance, for getSummary it will return (Request, Response, Result<List<Summary>, FuelError>)

In case of Java, an Handler function is used that have 2 callbacks : onSuccess & onError

• Synchronous method :

A Triple<Request, Response, T> object is returned.

Authentication status

val bboxapi = BboxApiRouter()

println("authentication attempts : ${bboxapi.attempts}")
println("user is authenticated   : ${bboxapi.authenticated}")
println("user is blocked         : ${bboxapi.blocked}")
println("ban expiration date     : ${bboxapi.blockedUntil}")

BboxApi bboxapi = new BboxApiRouter();

System.out.println("authentication attempts : " + bboxapi.getAttempts());
System.out.println("user is authenticated   : " + bboxapi.getAuthenticated());
System.out.println("user is blocked         : " + bboxapi.getBlocked());
System.out.println("ban expiration date     : " + bboxapi.getBlockedUntil());

There is an anti-bruteforce mechanism that prevents user from entering invalid password multiple times. When more than 2 attempts have been issued the next failure will report the next one by 120 seconds (unless you reboot the Bbox).

The following variables provide authentication status :

variable	type	default value	description
bboxapi.blocked	Boolean	false	true if there have been too many attempts
bboxapi.blockedUntil	Date	Date()	ban expiration date
bboxapi.attempts	Int	0	number of attempts so far
bboxapi.authenticated	Boolean	false	true if authenticated

API reference

Get Bbox Summary

Asynchronous

bboxapi.getSummary { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getSummary(new Handler<List<Summary>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Summary> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getSummarySync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Summary>, FuelError>> data = bboxapi.getSummarySync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Summary>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Retrieve Bbox Summary information which is an aggregation of all general API info including :

• voip
• hosts
• device info
• services
• display
• wireless
• usb
• diags
• wan

Get VOIP information

Asynchronous

bboxapi.getVoipInfo { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getVoipInfo(new Handler<List<Voip>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Voip> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getVoipInfoSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Voip>, FuelError>> data = bboxapi.getVoipInfoSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Voip>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Retrieve Voice over IP (VOIP) information including :

• voip status
• uri (which includes landline phone number)
• unread voice mail count
• voice mail count
• not answered voice mail count

Get Hosts

Asynchronous

bboxapi.getHosts { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getHosts(new Handler<List<Hosts>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Hosts> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getHostsSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Hosts>, FuelError>> data = bboxapi.getHostsSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Hosts>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Get a list of known hosts including :

• hostname
• mac address
• ip address
• link type (online/offline)
• host status (Device/STB)
• firstseen date
• lastseen date
• wireless info

Get device information

Asynchronous

bboxapi.getDeviceInfo { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getDeviceInfo(new Handler<List<Device>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Device> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getDeviceInfoSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Device>, FuelError>> data = bboxapi.getDeviceInfoSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Device>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Retrieve Bbox information including :

• box time
• status
• number of boots
• model name
• user configuration status (if user has set admin interface password)
• display luminosity
• version of services
• first use date
• uptime
• usage of ipv4, ipv6, adsl, ftth, vdsl

Get Call logs

Asynchronous

bboxapi.getCallLogs(line = Line.LINE1) { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getCallLogs(Line.LINE1, new Handler<List<CallLog>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<CallLog> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getCallLogsSync(line = Line.LINE1)
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<CallLog>, FuelError>> data = bboxapi.getCallLogsSync(Line.LINE1);

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<CallLog>, FuelError> obj = data.getThird();
System.out.println(obj.get());

replace Line.LINE1 with Line.LINE2 to get the call logs for second line

Retrieve full call logs since last reboot. Call logs information include the following info :

• call log id
• phone number
• call type (incoming/outgoing)
• answered status
• duration

Get wireless info

Asynchronous

bboxapi.getWirelessInfo { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getWirelessInfo(new Handler<List<Wireless>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Wireless> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getWirelessInfoSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Wireless>, FuelError>> data = bboxapi.getWirelessInfoSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Wireless>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Get wireless information including :

• status
• wifi 2.4Ghz & 5Ghz configurations
• channels
• ssid
• bssid
• wps
• security (wifi password, protocol & encryption)
• capabilities

Set wifi state

Asynchronous

bboxapi.setWifiState(state = true) { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(res.statusCode)
        }
    }
}

bboxapi.setWifiState(true, new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, res, result) = bboxapi.setWifiStateSync(state = true)
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        println(res.statusCode)
    }
}

Triple<Request, Response, Result<String, FuelError>> data = bboxapi.setWifiStateSync(true);

Request request = data.getFirst();
Response response = data.getSecond();
Result<String, FuelError> obj = data.getThird();
System.out.println(response.getStatusCode());

Enable or disable Wifi on Bbox

Set display state

Asynchronous

bboxapi.setDisplayState(state = true) { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(res.statusCode)
        }
    }
    latch.countDown()
}

bboxapi.setDisplayState(true, new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, res, result) = bboxapi.setDisplayStateSync(state = true)
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        println(res.statusCode)
    }
}

Triple<Request, Response, Result<String, FuelError>> data = bboxapi.setDisplayStateSync(true);

Request request = data.getFirst();
Response response = data.getSecond();
Result<String, FuelError> obj = data.getThird();
System.out.println(response.getStatusCode());

Set the Bbox luminosity display either to 0% or 100%

Voip dial

Asynchronous

bboxapi.voipDial(line = Line.LINE1, phoneNumber = "012345678") { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(res.statusCode)
        }
    }
}

bboxapi.voipDial(Line.LINE1, "0123456789", new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, res, result) = bboxapi.voipDialSync(line = Line.LINE1, phoneNumber = "012345678")
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        println(res.statusCode)
    }
}

Triple<Request, Response, Result<String, FuelError>> data = bboxapi.voipDialSync(Line.LINE1, "0123456789");

Request request = data.getFirst();
Response response = data.getSecond();
Result<String, FuelError> obj = data.getThird();
System.out.println(response.getStatusCode());

replace Line.LINE1 with Line.LINE2 to call on second line

Compose phone number on landline phone on line 1 or line 2 of Bbox. Also called click-to-call, the phone will ring & the call is triggered when someone pick up the phone

Reboot

Asynchronous

bboxapi.reboot { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(res.statusCode)
        }
    }
}

bboxapi.reboot(new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, res, result) = bboxapi.rebootSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        println(res.statusCode)
    }
}

Triple<Request, Response, Result<String, FuelError>> data = bboxapi.rebootSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<String, FuelError> obj = data.getThird();
System.out.println(response.getStatusCode());

Reboot Bbox

Get XDSL info

Asynchronous

bboxapi.getXdslInfo { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getXdslInfo(new Handler<List<Wan>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Wan> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getXdslInfoSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Wan>, FuelError>> data = bboxapi.getXdslInfoSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Wan>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Get information about link type including :

• state
• modulation
• showtime
• synchronization count

Get WAN info

Asynchronous

//asynchronous call
val latch = CountDownLatch(1)
bboxapi.getWanIpInfo { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getWanIpInfo(new Handler<List<Wan>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Wan> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.getWanIpInfoSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Wan>, FuelError>> data = bboxapi.getWanIpInfoSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Wan>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Information about WAN interface :

• internet state
• ip address
• gateway address
• dns servers
• ipv6
• mac address
• mtu
• link type (ADSL,VDSL,FTTH)

Set Wifi mac filter state

Asynchronous

bboxapi.setWifiMacFilter(state = false) { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println("wifi mac filter enabled ${res.statusCode}")
        }
    }
}

bboxapi.setWifiMacFilter(false, new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println("wifi mac filter enabled : " + response.getStatusCode());
    }
});

Synchronous

val (_, res, stateResult) = bboxapi.setWifiMacFilterSync(state = false)
when (stateResult) {
    is Result.Failure -> {
        val ex = stateResult.getException()
        println(ex)
    }
    is Result.Success -> {
        println("wifi mac filter enabled ${res.statusCode}")
    }
}

Triple<Request, Response, Result<String, FuelError>> result = bboxapi.setWifiMacFilterSync(false);

request = result.getFirst();
response = result.getSecond();
System.out.println("wifi mac filter enabled : " + response.getStatusCode());

Enable/Disable Wifi mac filtering

Get Wifi mac filter rules

Asynchronous

bboxapi.getWifiMacFilter { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.getWifiMacFilter(new Handler<List<Acl>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<Acl> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, wifiMacFilter) = bboxapi.getWifiMacFilterSync()
when (wifiMacFilter) {
    is Result.Failure -> {
        val ex = wifiMacFilter.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = wifiMacFilter.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<Acl>, FuelError>> data = bboxapi.getWifiMacFilterSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<Acl>, FuelError> wifiMacFilter = data.getThird();
System.out.println(wifiMacFilter.get());

Retrieve all mac filter rules

Create Wifi mac filter rule

Asynchronous

val rule1 = Acl.MacFilterRule(enable = true, macaddress = "01:23:45:67:89:01", ip = "")

bboxapi.createMacFilterRule(rule = rule1) { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println("create rule ${res.statusCode}")
        }
    }
}

Acl.MacFilterRule rule1 = new Acl.MacFilterRule(true, "01:23:45:67:89:01", "");

bboxapi.createMacFilterRule(rule1, new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println("created rule : " + response.getStatusCode());
    }
});

Synchronous

val rule2 = Acl.MacFilterRule(enable = true, macaddress = "34:56:78:90:12:34", ip = "")

val (_, res2, createResult) = bboxapi.createMacFilterRuleSync(rule = rule2)
when (createResult) {
    is Result.Failure -> {
        val ex = createResult.getException()
        println(ex)
    }
    is Result.Success -> {
        println("create rule ${res2.statusCode}")
    }
}

Acl.MacFilterRule rule2 = new Acl.MacFilterRule(true, "34:56:78:90:12:34", "");

Triple<Request, Response, Result<String, FuelError>> createdResult = bboxapi.createMacFilterRuleSync(rule2);
System.out.println("created rule : " + createdResult.getSecond().getStatusCode());

Create Wifi mac filter rule with the following information :

• state (enabled/disabled)
• mac address
• ip address

Update Wifi mac filter rule

Asynchronous

val rule2 = Acl.MacFilterRule(enable = true, macaddress = "34:56:78:90:12:34", ip = "")

bboxapi.updateMacFilterRule(ruleIndex = 1, rule = rule2) { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println("updated rule 1 ${res.statusCode}")
        }
    }
}

Acl.MacFilterRule rule2 = new Acl.MacFilterRule(true, "34:56:78:90:12:34", "");

bboxapi.updateMacFilterRule(1, rule2, new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println("updated rule 1 : " + response.getStatusCode());
    }
});

Synchronous

val rule1 = Acl.MacFilterRule(enable = true, macaddress = "01:23:45:67:89:01", ip = "")

val (_, res, updateResult) = bboxapi.updateMacFilterRuleSync(ruleIndex = 2, rule = rule1)
when (updateResult) {
    is Result.Failure -> {
        val ex = updateResult.getException()
        println(ex)
    }
    is Result.Success -> {
        println("updated rule 2 ${res.statusCode}")
    }
}

Acl.MacFilterRule rule1 = new Acl.MacFilterRule(true, "01:23:45:67:89:01", "");

Triple<Request, Response, Result<String, FuelError>> updateResult = bboxapi.updateMacFilterRuleSync(2, rule1);
System.out.println("updated rule 2 : " + updateResult.getSecond().getStatusCode());

Update Wifi mac filter with the following properties :

• state (enabled/disabled)
• mac address
• ip address

Delete Wifi mac filter rule

Asynchronous

bboxapi.deleteMacFilterRule(ruleIndex = 1) { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(res.statusCode)
        }
    }
}

bboxapi.deleteMacFilterRule(1, new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, res, result) = bboxapi.deleteMacFilterRuleSync(ruleIndex = 1)
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(res.statusCode)
    }
}

Triple<Request, Response, Result<String, FuelError>> result = bboxApi.deleteMacFilterRuleSync(1);

Response response = result.getSecond();

Delete wifi mac filter rule by index

Logout

Asynchronous

bboxapi.logout { _, response, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(response.statusCode)
        }
    }
}

bboxapi.logout(new Handler<byte[]>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, byte[] data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, response, result) = bboxapi.logoutSync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        println(response.statusCode)
    }
}

Triple<Request, Response, Result<byte[], FuelError>> data = bboxapi.logoutSync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<byte[], FuelError> obj = data.getThird();
System.out.println(response.getStatusCode());

Logout. This will set the authenticated state to false

Start password recovery

Asynchronous

bboxapi.startPaswordRecovery { _, response, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(response.statusCode)
        }
    }
}

bboxapi.startPaswordRecovery(new Handler<byte[]>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, byte[] data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, response, result) = bboxapi.startPaswordRecoverySync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        println(response.statusCode)
    }
}

Triple<Request, Response, Result<byte[], FuelError>> data = bboxapi.startPaswordRecoverySync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<byte[], FuelError> obj = data.getThird();
System.out.println(response.getStatusCode());

Start password recovery process. This call is usually followed by a polling on verifyPasswordRecovery to check if the user has pressed the Wifi button on Bbox

Verify password recovery

Asynchronous

bboxapi.verifyPasswordRecovery { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.verifyPasswordRecovery(new Handler<List<RecoveryVerify>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, List<RecoveryVerify> data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.verifyPasswordRecoverySync()
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<List<RecoveryVerify>, FuelError>> data = bboxapi.verifyPasswordRecoverySync();

Request request = data.getFirst();
Response response = data.getSecond();
Result<List<RecoveryVerify>, FuelError> obj = data.getThird();
System.out.println(obj.get());

Check the remaining time for the user to push the Wifi button on Bbox to set password. This API will return a List<RecoveryVerify> object only if the user has not pressed the button yet. When the user push the button, the next call to verifyPasswordRecovery will return an empty String (eg a null result) with the authentication cookie.

When an empty response (or a null result) is detected, you may want to reset password with resetPassword.

Reset password

Asynchronous

bboxapi.resetPassword(password = "123456") { _, res, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            println(res.statusCode)
        }
    }
}

bboxapi.resetPassword("123456", new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println(response.getStatusCode());
    }
});

Synchronous

val (_, res, result) = bboxapi.resetPasswordSync(password = "123456")
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(res.statusCode)
    }
}

Triple<Request, Response, Result<String, FuelError>> result = bboxApi.resetPasswordSync("123456");

Response response = result.getSecond();

Reset password by setting a new one

Custom HTTP request

Asynchronous

bboxapi.createCustomRequest(request = bboxapi.manager.request(method = Method.GET, path = "/summary"), auth = false) { _, _, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            println(ex)
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

bboxapi.createCustomRequest(bboxapi.getManager().request(Method.GET, "/summary", null), false, new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        error.printStackTrace();
    }

    @Override
    public void success(Request request, Response response, String data) {
        System.out.println(data);
    }
});

Synchronous

val (_, _, result) = bboxapi.createCustomRequestSync(request = bboxapi.manager.request(method = Method.GET, path = "/voip"), auth = true)
when (result) {
    is Result.Failure -> {
        val ex = result.getException()
        println(ex)
    }
    is Result.Success -> {
        val data = result.get()
        println(data)
    }
}

Triple<Request, Response, Result<String, FuelError>> data = bboxapi.createCustomRequestSync(bboxapi.getManager().request(Method.GET, "/voip", null), true);
System.out.println(data.getThird().get());

Create your own HTTP request, this can be useful for not relying on the library implementation

All request construction are prefixed with http://bbox.lan/api/v1 if host is not specified

Setting Password

The first time user connects to Bbox admin interface or when a user lose his/her password, the password should be resetted. User will have to do the following things :

• trigger a call to startPasswordRecovery, on the admin interface, this is done by clicking a button
• call verifyPasswordRecovery many times (polling) to check if user has pressed the button on Bbox device
• when user has pressed the button the next call to verifyPasswordRecovery will grant authentication
• a call to resetPassword("yourNewPassword") is used to set a new password

You can simply use waitForPushButton to wait for an amount of time for the user to press the button with a configurable polling interval (default 1 second)

val bboxapi = BboxApiRouter()
println("push the button on your Bbox for setting your password, you have 20 seconds")
val state = bboxapi.waitForPushButton(maxDuration = 20000)
if (state) {
    val setPasswordRes = bboxapi.resetPasswordSync(password = "admin2")
    println("set password : ${setPasswordRes.second.statusCode}")
}

BboxApi bboxapi = new BboxApiRouter();
System.out.println("push the button on your Bbox for setting your password, you have 20 seconds");
Boolean state = bboxapi.waitForPushButton(20000, 1000);
if (state) {
    Triple<Request, Response, Result<String, FuelError>> result = bboxapi.resetPasswordSync("123456");
    System.out.println("set password : " + result.component2().getStatusCode());
} else {
    System.out.println("didn't detect the push button");
}

Oauth2.0 (Experimental)

Oauth2.0 via push button

val bboxapi = BboxApiRouter(clientId = "client_id_test", clientSecret = "client_secret_test")
bboxapi.init()

val token = bboxapi.authenticateOauthButton(
        maxDuration = 20000,
        pollInterval = 1000,
        scope = listOf(Scope.ALL))
if (token != null) {
    //store bboxapi.oauthToken?.refresh_token
    println(token)
}

BboxApiRouter bboxapi = new BboxApiRouter("client_id_test", "client_secret_test");
bboxapi.init();

List<Scope> scope = new ArrayList<>();
scope.add(Scope.ALL);

OauthToken token = bboxapi.authenticateOauthButton(20000, 1000, scope);

if (token != null) {
    //store bboxapi.oauthToken?.refresh_token
    System.out.println(token);
}

You can request Oauth2.0 access token/refresh token via button push.

A call to authenticateOauthButton will wait for a button push. This will give a refresh token & an access token

Subsequent call to secured api endpoint will use this access token instead of the Basic auth Cookie. Afterwards, when secured call return 401, a refresh token request will be automatically issues before retrying the request with the new access token

User should store the refresh token in local storage (bboxapi.oauthToken?.refresh_token) when button is push so you can set it when you initialize BboxApiRouter the next time user start your app

Set refresh token manually

val bboxapi = BboxApiRouter(clientId = "client_id_test", clientSecret = "client_secret_test")
bboxapi.init()
bboxapi.oauthToken = OauthToken(
        access_token = "",
        refresh_token = "some refresh token you have stored",
        expires_in = 0,
        issued_at = "",
        token_type = "Bearer"
)

BboxApiRouter bboxapi = new BboxApiRouter("client_id_test", "client_secret_test");
bboxapi.init();
bboxapi.setOauthToken(new OauthToken(
        "", //access token
        "some refresh token you have stored", //refresh token
        "Bearer", //token type
        0, //expires_in
        "" //issues_at
));

Errors

check exception type & response status code on failure :

val bboxapi = BboxApiRouter()
bboxapi.setPassword("root")

bboxapi.getVoipInfo { _, response, result ->
    when (result) {
        is Result.Failure -> {
            val ex = result.getException()
            when {
                ex.exception is UnknownHostException -> println("hostname bbox.lan was not found")
                ex.exception is HttpException -> println("http error : ${response.statusCode}")
                else -> ex.printStackTrace()
            }
        }
        is Result.Success -> {
            val data = result.get()
            println(data)
        }
    }
}

BboxApi bboxapi = new BboxApiRouter();
bboxapi.setPassword("root");

bboxapi.getVoipInfo(new Handler<List<Voip>>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
        if (error.getException() instanceof UnknownHostException) {
            System.out.println("hostname bbox.lan was not found");
        } else if (error.getException() instanceof HttpException) {
            System.out.println("http error : " + response.getStatusCode());
        } else {
            error.printStackTrace();
        }
    }

    @Override
    public void success(Request request, Response response, List<Voip> data) {
        System.out.println(data);
    }
});

Replace "root" with your Bbox admin interface password

FuelError can be checked for exceptions, for instance :

Exception	description
UnknownHostException	http://bbox.lan host was not found on network
HttpException	a non 2XX HTTP response was received, check the status code from the response

Among HttpException, you can find the following :

Error Code	Meaning
400	Bad Request -- request format is invalid
401	Unauthorized -- password is invalid
404	Not Found -- endpoint doesn't exist (check it starts with http://bbox.lan/api/v1)
429	Too Many Requests -- too many fail login attempt, check the ban expiration date to retry more