diff options
| -rw-r--r-- | README.md | 164 |
1 files changed, 129 insertions, 35 deletions
@@ -1,35 +1,86 @@ # libimobiledevice -## About - -A library to communicate with services of Apple iOS devices using native -protocols. - -## Requirements - -Development Packages of: -* OpenSSL or GnuTLS -* libplist -* libusbmuxd - -Software: -* usbmuxd (OSS or Apple's version) -* make -* autoheader -* automake -* autoconf -* libtool -* pkg-config -* gcc or clang +*A library to communicate with services on iOS devices using native protocols.* + +## Features + +libimobiledevice is a cross-platform software library that talks the protocols +to interact with iOS devices. + +Unlike other projects, it does not depend on using any existing proprietary +libraries and does not require jailbreaking. + +Some key features are: + +- **Interface**: Implements many high-level interfaces for device services +- **Implementation**: Object oriented architecture and service abstraction layer +- **Cross-Platform:** Tested on Linux, macOS, Windows and Android platforms +- **Utilities**: Provides various command-line utilities for device services +- **SSL**: Allows choosing between OpenSSL or GnuTLS to handle SSL communication +- **Network**: Supports network connections with "WiFi sync" enabled devices +- **Python:** Provides Cython based bindings for Python + +The implemented interfaces of many device service protocols allow applications +to: + +* Access filesystem of a device +* Access documents of file sharing apps +* Retrieve information about a device and modify various settings +* Backup and restore the device in a native way compatible with iTunes +* Manage app icons arrangement on the device +* Install, remove, list and basically manage apps +* Activate a device using official serviers +* Manage contacts, calendars, notes and bookmarks +* Retrieve and remove crashreports +* Retrieve various diagnostics information +* Establish a debug connection for app debugging +* Mount filesystem images +* Forward device notifications +* Manage device provisioning +* Take screenshots from the device screen (requires mounted developer image) +* Simulate changed geolocation of the device (requires mounted developer image) +* Relay the syslog of the device +* Expose a connection for WebKit remote debugging + +... and much more. + +The library is in development since August 2007 with the goal to bring support +for these devices to the Linux Desktop. + +## Installation / Getting started + +### Debian / Ubuntu Linux + +First install all required dependencies and build tools: +```shell +sudo apt-get install \ + build-essential \ + checkinstall \ + git \ + autoconf \ + automake \ + libtool-bin \ + libplist-dev \ + libusbmuxd-dev \ + libssl-dev \ + usbmuxd +``` -Optional: -* cython (Python bindings) -* doxygen (Documentation) +If you want to optionally build the documentation or Python bindings use: +```shell +sudo apt-get install \ + doxygen \ + cython +``` -## Installation +Then clone the actual project repository: +```shell +git clone https://github.com/libimobiledevice/libimobiledevice.git +cd libimobiledevice +``` -To compile run: -```bash +Now you can build and install it: +```shell ./autogen.sh make sudo make install @@ -49,20 +100,63 @@ By default, OpenSSL will be used. If you prefer GnuTLS, configure with ./autogen.sh --disable-openssl ``` -## Who/What/Where? +## Usage + +Documentation about using the library in your application is not available yet. +The "hacker way" for now is to look at the implementation of the included +utilities. + +### Utilities + +The library bundles the following command-line utilities in the tools directory: + +| Utility | Description | +| -------------------------- | ------------------------------------------------------------------ | +| `idevice_id` | List attached devices or print device name of given device | +| `idevicebackup` | Create or restore backup for devices (legacy) | +| `idevicebackup2` | Create or restore backups for devices running iOS 4 or later | +| `idevicecrashreport` | Retrieve crash reports from a device | +| `idevicedate` | Display the current date or set it on a device | +| `idevicedebug` | Interact with the debugserver service of a device | +| `idevicedebugserverproxy` | Proxy a debugserver connection from a device for remote debugging | +| `idevicediagnostics` | Interact with the diagnostics interface of a device | +| `ideviceenterrecovery` | Make a device enter recovery mode | +| `ideviceimagemounter` | Mount disk images on the device | +| `ideviceinfo` | Show information about a connected device | +| `idevicename` | Display or set the device name | +| `idevicenotificationproxy` | Post or observe notifications on a device | +| `idevicepair` | Manage host pairings with devices and usbmuxd | +| `ideviceprovision` | Manage provisioning profiles on a device | +| `idevicescreenshot` | Gets a screenshot from the connected device | +| `idevicesetlocation` | Simulate location on device | +| `idevicesyslog` | Relay syslog of a connected device | + +Please consult the usage information or manual pages of each utility for a +documentation of available command line options and usage examples like this: +```shell +ideviceinfo --help +man ideviceinfo +``` + +## Links -* Home: https://libimobiledevice.org/ -* Code: `git clone https://git.libimobiledevice.org/libimobiledevice.git` -* Code (Mirror): `git clone https://github.com/libimobiledevice/libimobiledevice.git` -* Tickets: https://github.com/libimobiledevice/libimobiledevice/issues +* Homepage: https://libimobiledevice.org/ +* Repository: https://git.libimobiledevice.org/libimobiledevice.git +* Repository (Mirror): https://github.com/libimobiledevice/libimobiledevice.git +* Issue Tracker: https://github.com/libimobiledevice/libimobiledevice/issues * Mailing List: https://lists.libimobiledevice.org/mailman/listinfo/libimobiledevice-devel * Twitter: https://twitter.com/libimobiledev +## License + +This library and utilities are licensed under the [GNU Lesser General Public License v2.1](https://www.gnu.org/licenses/lgpl-2.1.en.html), +also included in the repository in the `COPYING` file. + ## Credits Apple, iPhone, iPod, and iPod Touch are trademarks of Apple Inc. -libimobiledevice is an independent software library and has not been -authorized, sponsored, or otherwise approved by Apple Inc. +This project is an independent software and has not been authorized, sponsored, +or otherwise approved by Apple Inc. -README Updated on: 2020-06-08 +README Updated on: 2020-06-12 |