#+TITLE:        MAXS Transport XMPP: User Guide
#+AUTHOR:       Florian Schmaus
#+EMAIL:        flo@geekplace.eu
#+OPTIONS:      author:nil
#+STARTUP:      noindent

* Overview

MAXS Transport XMPP acts as gateway between MAXS and the Extensible
Messaging and Presence Protocol (XMPP). It enables MAXS to receive
commands and send responses or notifications via XMPP.

For setup instructions go to [[../quickstart.org][projectmaxs.org/quickstart]]

** Permissions

| Permission                                | Use                                                                              |
|-------------------------------------------+----------------------------------------------------------------------------------|
| =android.permission.INTERNET=             | XMPP communication                                                               |
| =android.permission.ACCESS_NETWORK_STATE= | Detect and react on data connecvity changes                                      |
| =android.permission.ACCESS_WIFI_STATE=    | Bind a port ib the WiFi interfacefor a SOCKS5 proxy used for XMPP file transfers |

* XMPP

The *Extensible Messaging and Presence Protocol (XMPP)* is a
communications protocol based on XML. It was orginially named Jabber
and is used for near real-time, instant messaging between entities
(humans, embedded devices).

* XMPP Intent

MAXS Transport XMPP provides a service that allows Apps to send an
XMPP message by issuing an Intent. Since the service is not protected
by an permission, a shared token has to be specified for security
reasons.

The Intent action is
=org.projectmaxs.transport.xmpp.SEND_XMPP_MESSAGE=. The required
extras are

| Extra                                | Type   | Description                                                    |
|--------------------------------------+--------+----------------------------------------------------------------|
| org.projectmaxs.transport.xmpp.TOKEN | String | The shared token as set in the settings of MAXS Transport XMPP |
| org.projectmaxs.transport.xmpp.TO    | String | The JID of the message should be sent to                       |
| org.projectmaxs.transport.xmpp.BODY  | String | The body of the message                                        |

You can test the XMPP Intent with =adb=:
#+BEGIN_SRC bash
adb shell am startservice \
  -a org.projectmaxs.transport.xmpp.SEND_XMPP_MESSAGE \
  -e org.projectmaxs.transport.xmpp.TOKEN foo \
  -e org.projectmaxs.transport.xmpp.TO user@example.org \
  -e org.projectmaxs.transport.xmpp.BODY test
#+END_SRC
