contactSave: The phonebook backup
Function Description:
Back up your phone's contacts to the “tcbr/contacts” folder of the Total Control server (computer).
In Total Control 7.0.0 and later, it is supported to back up your contacts to xls, xlsx files.
Corresponding JS API:
contactSave(path)
contactSave(path,fields)
Whether to support multiple devices:
No
Version:
For Total Control version 6.9.0 and higher
Resource Information:
Method | POST |
---|---|
URL | 1. For Total Control version 6.9.0 and higher .../devices/:device/contacts?type=import 2. For Total Control version 7.0.0 and higher .../devices/:device/contacts?type=import&file_name=:file_name&fields=:fields |
Requires authentication? | Yes |
Method Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
device | String | Yes | ID value of the device |
type | String | Yes | A fixed value: import. |
file_name | String | No | The name of the backup address book file, supports .json, .xls, .xlsx formats. |
fields | Array | No | Back up the fields specified in the contact details. If you do not fill in, restore all fields. If you only restore some fields, you must also include the name and a phone number field.
For example, if we want to save the company field, the value of this parameter is: ['name', 'phone1', 'company'] |
Response Parameters:
A JSON string representing an array of objects with the following fields:
Field | Type | Description |
---|---|---|
status | Boolean | Return true for success and null for failure |
value | String | If the value of status is a null object, an error message or empty string is returned. If the value of status is true,it returns the location of the backed up contact file, this file is saved in the “tcbr/contacts” folder of the Total Control server (computer). For example: %AppData%\TotalControl\v1\storage\tcbr\contacts |
Request Example:
http://localhost:8090/TotalControl/v1/devices/device@230441652/contacts?type=import&token=tH3Q1p9aMjJoG3eP
Response Example:
If this API executes successfully, it returns:
{
"status": true,
"value": "http://localhost:8090/TotalControl/v1/storage/tcbr/contacts/HUAWEI-HUAWEI P7-L07-2018-29-02-14-29-00.json"
}
If the value of HTTP status code is 200, but the value of status is a null object, it returns:
{
"status": null,
"value": "<Error message>"
}
JSON: If the backed up file is in JSON format, the contents of the json file are as follows:
{
"version": "1.0.0.0",
"data": [{
"contactId": "16",
"displayName": "Amy",
"phone": [{
"phoneNumber": "028 8533 0000",
"phoneType": "2"
}],
"email": [],
"organization": [],
"iconBytes": ""
},
{
"contactId": "2",
"displayName": "huawei",
"phone": [{
"phoneNumber": "4008308300",
"phoneType": "2"
}, {
"phoneNumber": "10086",
"phoneType": "1"
}],
"email": [{
"emailValue": "mobile@huawei.com",
"emailType": "1"
}],
"organization": [],
"iconBytes": ""
}]
}
EXCEL:
If the backed up file is in EXCEL format, and the first line of the excel file consists of the following fields:name, phone1, phoneType1, phone2, phoneType2, phone3, phoneType3, email1, emailType1, email2, emailType2, company, title, iconBytes.
If you only save the company field, the first line of the excel file is:: 'name', 'phone1', 'company'
The contents of the excel file are as follows:
name | phone1 | phoneType1 | phone2 | phoneType2 | email1 | emailType1 | company | title |
Amy | 028 8888 6666 | 1 | amy@139.com | 1 | ||||
Tom | 1586668888 | 2 | sigma | tester |
Example:
Warm tip:
Get the token needed for Total Control script development,see here.
Get the id value of the master device, see here.
RingoJS Example:
// Import the packages
var {request} = require("ringo/httpclient");
var base64 = require("ringo/base64");
// The username and password are separated by a single : and sent on the wire base64 encoded
var userpass = base64.encode("sigma:3D391497");
// First step: Get the API token
var gettoken = request({
method: "GET",
url: "http://localhost:8090/TotalControl/v1/login",
headers: {
"Authorization": userpass
}
});
var ret_token = JSON.parse(gettoken.content);
var token = ret_token.value.token;
print("//The value of token is:" + token);
// Second step: Get the device id value of the master device
var getdevice = request({
method: "GET",
url: "http://localhost:8090/TotalControl/v1/devices/main?token=" + token
});
var device = JSON.parse(getdevice.content).id;
print("//The value of device ID is:"+ device);
// Third step: Execute this REST API
var resp = request({
method: "POST",
url: "http://localhost:8090/TotalControl/v1/devices/" + device + "/contacts",
data: {
"type": "import",
"file_name": "mycontact3.xls",
"fields": "['name','phone1','company']",
"token": token,
}
});
var obj = JSON.parse(resp.content);
var ret = obj.status;
if (ret == true) {
print("//Executed successfully,Return value: \n"+resp.content);
} else if (ret != true & resp.status == 200){
print("An error message is returned: "+resp.content);
} else {
print("This API failed to execute.");
}
The running result of the RingoJS:
If it executes successfully, it will return:
//The value of token is:R6x0t15Wt7aN97Y9
//The value of device ID is:device@33254183
//Executed successfully,Return value:
{"value":"http://127.0.0.1:8090/TotalControl/v1/storage/tcbr/contacts/mycontact3.xls","status":true}
Python Example:
#!/user/bin/python
#-*- coding:utf-8 -*-
import base64
import requests
# The username and password are separated by a single : and sent on the wire base64 encoded
user_pass = 'sigma:3D391497'
encodeStr = base64.b64encode(user_pass.encode("UTF-8"))
# First step: Get the API token
LoginUrl = "http://localhost:8090/TotalControl/v1/login"
response = requests.get(LoginUrl, headers={'Authorization':encodeStr})
print("Get the token,Return value: ",response.json())
token = response.json()['value']['token']
print("The value of token is: ",token)
# Second step: Get the device id value of the master device
if token is not None:
GetDeviceUrl = "http://localhost:8090/TotalControl/v1/devices/main?token=" + token
response = requests.get(url=GetDeviceUrl)
print("Get the device id,Return value: ", response.json())
device = response.json()['id']
print("The value of device id is: ", device)
if device is not None:
# Third step: Execute this REST API
APIUrl = "http://localhost:8090/TotalControl/v1/devices/" + device + "/contacts"
data = {
"type": "import",
"file_name": "mycontact1.xls",
"fields": "['name','phone1','company']",
"token": token
}
response = requests.post(url=APIUrl, params=data)
ret = response.json()['status']
# Determine if this REST API is executed successfully
if ret is True:
print("Executed successfully,Return value: ", response.json())
elif response.status_code == 200 and ret is not True:
print("An error message is returned: ",response.json())
else:
print("This API failed to execute.")
else:
print("Failed to get device id.")
else:
print("Failed to get token.")
The running result of the python:
If it executes successfully, it will return:
Get the token,Return value: {'status': True, 'value': {'token': 'R6x0t15Wt7aN97Y9'}}
The value of token is: R6x0t15Wt7aN97Y9
Get the device id,Return value: {'id': 'device@33254183'}
The value of device id is: device@33254183
Executed successfully,Return value: {'value': 'http://127.0.0.1:8090/TotalControl/v1/storage/tcbr/contacts/mycontact1.xls', 'status': True}