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 functiongetSummarySync
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
withLine.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
withLine.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 |