Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
Added Teleport library
- Loading branch information
1 parent
24fc395
commit b121725
Showing
61 changed files
with
2,669 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
# built application files | ||
#*.apk | ||
*.ap_ | ||
|
||
# files for the dex VM | ||
*.dex | ||
|
||
# Java class files | ||
*.class | ||
|
||
# generated files | ||
bin/ | ||
gen/ | ||
out/ | ||
|
||
|
||
# Ignored by AndroidStudio | ||
*.iws | ||
*.iml | ||
|
||
# Folders related to builds and Gradle | ||
.gradle/ | ||
*/build/ | ||
build/ | ||
|
||
# Local settings (regenerated by Android Studio) | ||
.idea/ | ||
local.properties | ||
demo/apk/ | ||
|
||
#Personal Files | ||
signing.properties | ||
lic.properties |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,170 @@ | ||
# Teleport - Data Sync & Messaging Library for Android Wear | ||
|
||
![Screen](/doc/images/teleport_256.png) | ||
|
||
Teleport is a library to easily setup and manage Data Syncronization and Messaging on Android Wearables. | ||
|
||
*The library is thought for Android Studio.* | ||
|
||
|
||
|
||
##Quick Overview | ||
|
||
You can see Teleport as an Android Wear "plugin" you can add to your Activities and Services. | ||
|
||
Teleport provides you **commodity classes** to easily establish a communication between a mobile handheld device and an Android Wear device. | ||
|
||
* `TeleportClient` provides you "endpoints" you can put inside your Activities, both in Mobile and Wear. | ||
* `TeleportService` is a full-fledged, already set-up 'WearableListenerService'. | ||
|
||
Both these classes incapsulates all the `GoogleApiClient` setup required to establish a connection between Mobile and Wear. | ||
|
||
`TeleportClient` and `TeleportService` also provide you two `AsyncTask` you can extend to easily perform operations with the synced DataItems and received Messages: | ||
|
||
* `OnSyncDataItemTask` provides you a complete `DataMap` of synced data | ||
* `OnGetMessageTask` provides you access to a received Message `path` in form of `String`. | ||
|
||
You just need to *extend* these tasks inside your Activity/Service and you're good to go! | ||
|
||
To Sync Data and send Messages, you can use commodity methods like | ||
|
||
* `sync<ItemType>(String key, <ItemType> item)` to Sync Data across devices | ||
* `sendMessage(String path, byte[] payload)` to send a Message to another device. | ||
|
||
##Summary | ||
|
||
* [Library Set Up:](/doc/SETUP.md) How to import Teleport library in your project. | ||
* [TeleportClient in Activity:](/doc/TELEPORTCLIENT.md) How to setup a TeleportClient. | ||
* [TeleportService:](/doc/TELEPORTSERVICE.md) How to setup a TeleportService. | ||
* [Sync Data:](/doc/SYNCDATA.md) How to Sync Data | ||
* [Send and Receive Messages:](/doc/MESSAGE.md) How to Send and Receive Messages | ||
* [Advanced Usage:](/doc/ADVANCEDUSAGE.md) AsyncTask Factory and Callbacks | ||
|
||
##Can I have an example of how easy is Teleport to use? | ||
|
||
There you go :-) | ||
|
||
Here's a *Mobile and a Wear Activity* already configured to Sync Data. | ||
|
||
* The MobileActivity synchronizes a string "Hello, World!". | ||
* The WearActivity shows a Toast with the synchronized string. | ||
|
||
###MobileActivity.java | ||
```java | ||
|
||
public class MobileActivity extends Activity { | ||
|
||
TeleportClient mTeleportClient; | ||
|
||
@Override | ||
protected void onCreate(Bundle savedInstanceState) { | ||
super.onCreate(savedInstanceState); | ||
setContentView(R.layout.activity_mobile); | ||
|
||
mTeleportClient = new TeleportClient(this); | ||
} | ||
|
||
@Override | ||
protected void onStart() { | ||
super.onStart(); | ||
mTeleportClient.connect(); | ||
} | ||
|
||
@Override | ||
protected void onStop() { | ||
super.onStop(); | ||
mTeleportClient.disconnect(); | ||
} | ||
|
||
|
||
public void syncDataItem(View v) { | ||
//Let's sync a String! | ||
mTeleportClient.syncString("hello", "Hello, World!"); | ||
} | ||
|
||
} | ||
``` | ||
|
||
###WearActivity.java | ||
|
||
```java | ||
|
||
public class WearActivity extends Activity { | ||
|
||
TeleportClient mTeleportClient; | ||
|
||
@Override | ||
protected void onCreate(Bundle savedInstanceState) { | ||
super.onCreate(savedInstanceState); | ||
setContentView(R.layout.activity_wear); | ||
|
||
mTeleportClient = new TeleportClient(this); | ||
|
||
mTeleportClient.setOnSyncDataItemTask(new ShowToastHelloWorldTask()); | ||
|
||
} | ||
|
||
@Override | ||
protected void onStart() { | ||
super.onStart(); | ||
mTeleportClient.connect(); | ||
} | ||
|
||
@Override | ||
protected void onStop() { | ||
super.onStop(); | ||
mTeleportClient.disconnect(); | ||
|
||
} | ||
|
||
public class ShowToastHelloWorldTask extends TeleportClient.OnSyncDataItemTask { | ||
|
||
@Override | ||
protected void onPostExecute(DataMap dataMap) { | ||
|
||
String hello = dataMap.getString("hello"); | ||
|
||
Toast.makeText(getApplicationContext(),hello,Toast.LENGTH_SHORT).show(); | ||
} | ||
} | ||
|
||
} | ||
``` | ||
|
||
Jump to [Library Set Up](/doc/SETUP.md) !!! | ||
|
||
##Follow me on | ||
Author: Mario Viviani | ||
<a href="https://plus.google.com/+MarioViviani/posts"> | ||
<img alt="Follow me on Google+" | ||
src="https://github.com/Mariuxtheone/Teleport/raw/master/doc/images/googleplus64.png" /> | ||
</a> | ||
<a href="https://it.linkedin.com/pub/mario-viviani/45/b96/a59/"> | ||
<img alt="Follow me on LinkedIn" | ||
src="https://github.com/Mariuxtheone/Teleport/raw/master/doc/images/linkedin64.png" /> | ||
</a> | ||
|
||
##Thanks to: | ||
Damien Cavaillès - https://github.com/thedamfr | ||
|
||
|
||
##License | ||
|
||
Teleport is released under the **Apache License 2.0** | ||
|
||
Copyright 2014-2015 Mario Viviani | ||
|
||
Licensed under the Apache License, Version 2.0 (the "License"); | ||
you may not use this file except in compliance with the License. | ||
You may obtain a copy of the License at | ||
|
||
http://www.apache.org/licenses/LICENSE-2.0 | ||
|
||
Unless required by applicable law or agreed to in writing, software | ||
distributed under the License is distributed on an "AS IS" BASIS, | ||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
See the License for the specific language governing permissions and | ||
limitations under the License. | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
// Top-level build file where you can add configuration options common to all sub-projects/modules. | ||
|
||
buildscript { | ||
repositories { | ||
jcenter() | ||
} | ||
dependencies { | ||
classpath 'com.android.tools.build:gradle:1.0.0-rc4' | ||
|
||
|
||
// NOTE: Do not place your application dependencies here; they belong | ||
// in the individual module build.gradle files | ||
} | ||
} | ||
|
||
allprojects { | ||
repositories { | ||
jcenter() | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
#ADVANCED USAGE | ||
|
||
## Using AsyncTask Factory | ||
|
||
AsyncTask are single shot. | ||
|
||
Most of the time it will be okay with the basic use. But if you are using Message or DataSyncing with at a **certain rate or running on a low end phone**, you might be running into a corner case. | ||
|
||
Sometime, the event come and the AsyncTask is still currently running and it ends in a Exception. | ||
|
||
There you should not use classical setters but use the `Builder` setter. | ||
|
||
Each AsyncTask is provided with an appropriate builder. The main purpose is that every time a new event is triggered, a new AsyncTask will be instantiated automatically. | ||
|
||
```java | ||
mTeleportClient.setOnGetMessageTaskBuilder ( | ||
new OnGetMessageTask.Builder () { | ||
@Override | ||
public void build() { | ||
return new ShowToastAsyncTask(); | ||
} | ||
} | ||
); | ||
|
||
|
||
mTeleportClient.setOnSyncDataItemTaskBuilder ( | ||
new OnSyncDataItemTask.Builder () { | ||
@Override | ||
public void build() { | ||
return new ShowToastAsyncTask(); | ||
} | ||
} | ||
); | ||
``` | ||
|
||
##Using Callbacks | ||
|
||
If you want to manage yourself the response of Data sync or Message received, you can use Callbacks. There are `OnGetMessageCallback` and `OnSyncDataItemCallback` you can set in your `TeleportClient` and `TeleportService`. | ||
|
||
Remember: in this case you need to **manage the threading yourself!**. Callbacks are not asynchronous like AsyncTask and AsyncTask Factory. | ||
|
||
``` java | ||
//OnGetMessageCallback | ||
mTeleportClient.setOnGetMessageCallback(new TeleportClient.OnGetMessageCallback() { | ||
@Override | ||
public void onCallback(String dataMap) { | ||
//your callback here... | ||
} | ||
}); | ||
|
||
//OnGetMessageCallback | ||
mTeleportClient.setOnSyncDataItemCallback(new TeleportClient.OnSyncDataItemCallback() { | ||
@Override | ||
public void onDataSync(DataMap dataMap) { | ||
//your callback here... | ||
} | ||
}); | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,70 @@ | ||
#Send and Receive Messages | ||
|
||
##Send Messages | ||
|
||
To send a Message to another device, you can use the method `sendMessage(String path, byte[] payload)` | ||
|
||
provided by `TeleportClient` and `TeleportService`. | ||
|
||
|
||
*Example:* if you want to send a "startActivity" message, you can do it this way | ||
|
||
``` java | ||
|
||
mTeleportClient.sendMessage("startActivity", null); | ||
``` | ||
|
||
You can use the `payload` argument to attach a payload (100KB max) to your message (at the moment the Payload is not used by Teleport) | ||
|
||
##Listen and react to Messages | ||
|
||
`TeleportClient` and `TeleportService` provide you a custom async tasks `OnGetMessageTask` that react to received Messages | ||
|
||
**You need to *extend* these abstract Task inside your Activity, implementing the `OnPostExecute()` method.** | ||
|
||
|
||
###OnSyncDataItemTask | ||
|
||
`OnGetMessageTask` allows you to easily get the path of a received Message. | ||
|
||
**Example:**, let's say we want to start an Activity when the String with the `path` "startActivity" is synced: | ||
|
||
We just need to extend `OnSyncDataItemTask` like this: | ||
|
||
``` java | ||
|
||
private static final String STARTACTIVITY = "startActivity"; | ||
|
||
public class StartActivityTask extends TeleportClient.OnGetMessageTask { | ||
|
||
@Override | ||
protected void onPostExecute(String path) { | ||
|
||
if (path.equals(STARTACTIVITY)){ | ||
Intent startIntent = new Intent(getBaseContext(), WearActivity.class); | ||
startIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); | ||
startActivity(startIntent); | ||
} | ||
|
||
} | ||
} | ||
``` | ||
|
||
Easy, right? ;-) | ||
|
||
*NOTE: Remember that a AsyncTask will be executed only once, so you might need to **reset the task** if you want to perform it again.* | ||
|
||
###Set the OnGetMessageTask | ||
|
||
After we`ve implemented our Task, we need to **set it in our TeleportClient/Service**. | ||
|
||
`TeleportClient/Service` provide you with a method `setOnGetMessageTask(OnGetMessageTask onGetMessageTask)` to set up the task. | ||
|
||
You can add it where you want, for example to your Activity `onCreate()` like this (following the above example): | ||
|
||
``` java | ||
|
||
mTeleportClient.setOnGetMessageTask(new StartActivityTask()); | ||
``` | ||
|
||
If you need more advanced usage, you can use AsyncTask Factory or Callbacks. Learn more here: [Advanced Usage](/doc/ADVANCEDUSAGE.md) |
Oops, something went wrong.