Skip to content

Commit f042c0d

Browse files
author
Oscar Henry Tejera
authored
Update README.md
1 parent 99f6f47 commit f042c0d

File tree

1 file changed

+131
-9
lines changed

1 file changed

+131
-9
lines changed

‎README.md‎

Lines changed: 131 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
# Overview #
22

3-
This is a simple "REST" (I'm not so sure about that) service wrapper of [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice) to communicate with services of Apple iOS devices using native
3+
**java-http-libimobiledevice** is a simple "REST" (I'm not so sure about that) service wrapper of [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice) to communicate with services of Apple iOS devices using native
44
protocols. This service works on Linux and macOS.
55

6+
**libimobiledevice** is a cross-platform software library that talks the protocols to support iPhone®, iPod Touch®, iPad® and Apple TV® devices. Unlike other projects, it does not depend on using any existing proprietary libraries and does not require jailbreaking. It allows other software to easily access the device's filesystem, retrieve information about the device and it's internals, backup/restore the device, manage SpringBoard® icons, manage installed applications, etc.
7+
68
## Requirements
79

810
Install **libimobiledevice**:
911

1012
**Linux (Ubuntu)**
1113
```bash
12-
1314
sudo add-apt-repository ppa:pmcenery/ppa
1415
sudo apt-get update
1516
sudo apt-get install libimobiledevice
@@ -18,17 +19,15 @@ sudo apt-get install libimobiledevice-utils
1819

1920
**macOS**
2021
```bash
21-
2222
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null
2323
brew install libimobiledevice
2424
```
2525

2626
## Configuration
2727

28-
We need to set the libimobiledevice binaries path. In order to know this path open a terminal and execute:
28+
We need to set the **libimobiledevice** binaries path. In order to know this path open a terminal and execute:
2929

3030
```bash
31-
3231
whereis ideviceinfo
3332
```
3433

@@ -43,16 +42,139 @@ libimobiledevice.timeout=20000
4342
## Execution
4443

4544
* Download the latest version
46-
* Place the **ios-service.config** configuration file in the folder where **ios-service-X.X.X.jar** is located.
45+
* Place the **ios-service.config** configuration file in the folder where **java-http-libimobiledevice-X.X.X.jar** is located.
4746
* Start service:
4847

4948
```bash
49+
java -jar java-http-libimobiledevice-X.X.X.jar
50+
```
51+
52+
## URL structure
53+
54+
The java-http-libimobiledevice API lives at [http://127.0.0.1:5050/api/v1/](http://127.0.0.1:5050/api/v1/), with particular endpoints following that prefix.
55+
56+
Responses are in **JSON**
57+
58+
## Example calls
59+
60+
API examples use [httpie](https://httpie.org), a command-line HTTP client.
5061

51-
sudo sudo service ios-service start
62+
Gets information about the battery of an attached device.
63+
64+
**:serial** = Target specific device by its 40-digit device UDID.
65+
66+
```bash
67+
http http://127.0.0.1:5050/api/v1/device/:serial/battery
68+
```
69+
**Response**
70+
71+
```json
72+
{
73+
"data": {
74+
"currentCapacity": 100,
75+
"externalChargeCapable": true,
76+
"externalConnected": true,
77+
"fullyCharged": false,
78+
"gasGaugeCapability": true,
79+
"health": "good",
80+
"isCharging": false,
81+
"temp": "0"
82+
}
83+
}
5284
```
5385

54-
* Send a GET request to http://ip:5005/api/v1/devices in order to verify that the service is running.
86+
Retrieve the CPU Architecture from the target device.
5587

5688
```bash
57-
curl http://127.0.0.1:5005/api/v1/devices
89+
http http://127.0.0.1:5050/api/v1/device/:serial/cpu/architecture
5890
```
91+
**Response**
92+
93+
```json
94+
95+
{
96+
"data": {
97+
"architecture": "armv7f",
98+
"status": "Success"
99+
}
100+
}
101+
```
102+
Get a device
103+
104+
Retrieve the CPU Architecture from the target device.
105+
106+
```bash
107+
http http://127.0.0.1:5050/api/v1/device/:serial
108+
```
109+
**Response**
110+
111+
```json
112+
113+
{
114+
"data":{
115+
"architecture": "armv7f",
116+
"battery": {
117+
"currentCapacity": 100,
118+
"externalChargeCapable": true,
119+
"externalConnected": true,
120+
"fullyCharged": false,
121+
"gasGaugeCapability": true,
122+
"health": "good",
123+
"isCharging": false,
124+
"temp": "0"
125+
},
126+
"disk": {
127+
"amountDataAvailable": 2901368832.0,
128+
"amountDataReserved": 209715200.0,
129+
"calculateDiskUsage": "null",
130+
"calendarUsage": 0.0,
131+
"cameraUsage": 0.0,
132+
"mediaCacheUsage": 0.0,
133+
"notesUsage": 0.0,
134+
"photoUsage": 0.0,
135+
"totalDataAvailable": 3111084032.0,
136+
"totalDataCapacity": 13924319232.0,
137+
"totalDiskCapacity": 15955132416.0,
138+
"totalSystemAvailable": 272629760.0,
139+
"totalSystemCapacity": 2030813184.0,
140+
"voicemailUsage": 0.0,
141+
"webAppCacheUsage": 0.0
142+
},
143+
"model": "iPad",
144+
"manufacturer": "Apple",
145+
"platform": "ios",
146+
"platformVersion": "8.4.1",
147+
"present": true,
148+
"ready": true,
149+
"status" : 3,
150+
"serial": "0416d649d4c1b9b57e0dae22a42344926a1dcc74",
151+
"state": "available"
152+
}
153+
}
154+
}
155+
```
156+
157+
# API Documentation
158+
159+
We use [apiDoc](http://apidocjs.com/) in order to generate the [documentation](https://mobileboxlab.github.io/java-http-libimobiledevice/) for java-http-libimobiledevice’s HTTP API.
160+
161+
**apiDoc** creates a documentation from API annotations in your source code. Please check the documentation [here](http://apidocjs.com/#params)
162+
163+
The proyect come with a Maven task in order to generate the documentation from Maven without any pain, but FIRST you need install **apiDoc** of course:
164+
165+
```bash
166+
npm install apidoc -g
167+
```
168+
169+
And now we need execute the following command:
170+
171+
```bash
172+
mvn exec:exec
173+
```
174+
175+
The documentation is generated on the **doc** directory.
176+
177+
## Contribution
178+
179+
Any ideas are welcome. Feel free to submit any issues or pull requests.
180+

0 commit comments

Comments
 (0)