matrix-org / matrix-android-sdk

This SDK is deprecated and the core team does not work anymore on it.

We strongly recommends that new projects use the new Android Matrix SDK.

A meglévő projektek számára, amelyek még mindig ezt az SDK-t használják, azonban a legjobb tudásunk szerint tudunk támogatást nyújtani.

matrix-android-sdk

Az Android SDK a Matrix REST API hívásait aszinkron Java metódusokba csomagolja, és alapvető struktúrákat biztosít az adatok tárolásához és kezeléséhez.

Ez egy Android Studio (gradle) projekt, amely tartalmazza az SDK modult.https://github.com/vector-im/riot-android Ez az SDK-t használó mintaalkalmazás.

Áttekintés

A Matrix API-k több kategóriára oszlanak (lásd ).Az alapvető használat a következő:

1. Login in or register to a home server -> get the user’s credentials
2. Start a session with the credentials
3. Start listening to the event stream
4. Make matrix API calls

Bugs / Feature Requests

Think you’ve found a bug? Kérjük, ellenőrizze, hogy nem létezik-e még issuedoes, majd ha nem, nyisson problémát ebben a Github repóban. Ha már létezik issue, nyugodtan szavazz rá.

Hozzájárulás

Hibát szeretne javítani vagy új funkciót hozzáadni? Ellenőrizd, hogy van-e már egy megfelelő nyitott hiba.Ha senki sem dolgozik aktívan a problémán, akkor a javításod megírásakor kérlek a develop ágba lépj, és nyiss egy pull requestet, ha készen állsz. Ne a master-ra alapozd a pull request-jeidet.

Bejelentkezés

A bejelentkezéshez használd a login API kliens egy példányát.

HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());

A sikeres bejelentkezés esetén a callback megadja a felhasználó hitelesítő adatait, amelyeket ezentúl használni kell.

Mátrix munkamenet indítása

A munkamenet egy felhasználó munkamenetét jelenti egy adott home szerverrel. Több fiók kezeléséhez potenciálisan több munkamenet is létezhet.

MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();

Egy munkamenetet hoz létre a home szerverrel való interakcióhoz.

A munkamenet hozzáférést biztosít a különböző API-khoz a REST klienseken keresztül:

session.getEventsApiClient() az események API-hoz

session.getProfileApiClient() a profil API-hoz

session.getPresenceApiClient() a jelenlét API-hoz

session.getRoomsApiClient() a szobák API-hoz

A módszerek teljes listáját lásd a .

PéldaEgy csevegőszoba tagjainak listájának lekérdezése valahogy így nézne ki:

session.getRoomsApiClient().getRoomMembers(<roomId>, callback);

Az egyes kérésekhez ugyanazt a munkamenetobjektumot kell használni. Ehhez szükség lehet egy singleton használatára, lásd a Matrix singletont a app modulban egy példát.

Az eseményfolyam

Minden Matrix-képes alkalmazás egyik fontos része lesz az eseményfolyam figyelése, az események (üzenetek, állapotváltozások stb.) élő áramlása.Erre szolgál:

session.startEventStream();

Ez elindítja az eseményszálat, és beállítja, hogy az eseményeket egy alapértelmezett hallgatónak küldje el.Hasznos lehet ezt egy Android Service-vel együtt használni annak ellenőrzésére, hogy az eseményfolyam a háttérben fusson-e vagy sem.

Az adatkezelő

Az adatkezelő egy réteget biztosít az eseményfolyam adatainak kezeléséhez. Bár lehetséges nodata handlerrel rendelkező alkalmazást írni és manuálisan API-hívásokat végrehajtani, az alkalmazás használata a legtöbb felhasználás esetén erősen ajánlott. Az adatkezelő :

• Kezeli az eseményfolyamból származó eseményeket
• Tárolja az adatokat a tárolási rétegében
• Megadja az eszközt egy alkalmazás számára, hogy visszahívásokat kapjon az eseményekhez
• Megadja és karbantartja a teremobjektumokat a teremspecifikus műveletekhez (üzenetek fogadása, csatlakozás, rugdosás, meghívás stb.)

MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());

Elkészít egy adatkezelőt az alapértelmezett memórián belüli tárolási implementációval.

Egy figyelő regisztrálása

Az eseményekről való értesítéshez az alkalmazásnak eseményhallgatót kell implementálnia.

session.getDataHandler().addListener(eventListener);

Ez a listener a MXEventListener alosztályba tartozik, és szükség szerint felülírja a metódusokat:

onPresenceUpdate(event, user) Elindul, ha egy felhasználó jelenléte frissült.

onLiveEvent(event, roomState) Elindul, ha egy élő esemény érkezik az eseményfolyamba.

onBackEvent(event, roomState) Elindul, ha egy régi esemény (az előzményekből) vagy visszamenőleges esemény érkezett vissza, miután több előzményt kértek.

onInitialSyncComplete() Elindul, ha a kezdeti szinkronizálási folyamat befejeződött. A kezdeti szinkronizálás az eseményfolyam első hívása az összes ismert szoba, felhasználó stb. állapotának inicializálására.

A Room objektum

A Room objektum metódusokat biztosít a szobával való interakcióhoz (üzenettörténet lekérése, csatlakozás stb.).

Room room = session.getDataHandler().getRoom(roomId);

megkapja (vagy létrehozza) az adott szoba azonosítóhoz tartozó szobaobjektumot.

Room state

A RoomState objektum a szoba egy adott időpontban fennálló állapotát reprezentálja: a szoba neve, témája, láthatósága (nyilvános/magán), tagjai stb. onLiveEvent és onBackEvent callbackek (lásd Hallgató regisztrálása) visszaadják az eseményt, de a szoba állapotát is az esemény időpontjában, hogy kontextusként szolgáljon a megjelenítés felépítéséhez (pl. a felhasználó megjelenített neve az üzenete idején). A megadott állapot az esemény feldolgozása előtti állapot, ha az esemény történetesen megváltoztatja a szoba állapotát.

Room history

A szobába való belépéskor egy alkalmazás általában a legutóbbi üzeneteket szeretné megjeleníteni. Ez a

room.requestHistory();

meghívásával történik, majd az események a onBackEvent(event, roomState) visszahíváson keresztül fordított sorrendben (legfrissebb először) kerülnek visszaadásra.

Ez nem váltja ki a szoba teljes előzményének visszaadását, hanem csak körülbelül 15 üzenetét. A requestHistory() ismételt hívása utána visszakapja a következő (korábbi) kb. 15-öt, és így tovább. Az előzmények lekérdezésének megkezdéséhez az aktuális élő állapotból (pl. egy szoba megnyitásakor vagy újranyitásakor),

room.initHistory();

az előzmények lekérdezése előtt meg kell hívni.

A tartalomkezelő

A mátrix home szerverek tartalom API-t biztosítanak a tartalom (képek, videók, fájlok stb.) letöltéséhez és feltöltéséhez.A tartalomkezelő biztosítja a burkolatot ezen API körül.

session.getContentManager();

Kérdezi az adott munkamenethez tartozó tartalomkezelőt.

Tartalom letöltése

A háziszerveren elhelyezett tartalmat (az eseményekben, avatár URL-ekben stb.) egy mxc-sémájú URI azonosítja (például mxc://matrix.org/xxxxxx).A tartalom lekérdezéséhez a mögöttes HTTP URI-t a

contentManager.getDownloadableUrl(contentUrl);

használatával lehet megkapni, ahol a contentUrl az mxc:// tartalom URL.

A képek esetében létezik egy további módszer a teljes méretű képek helyett a miniatűrök visszaadására:

contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);

amely lehetővé teszi egy adott szélesség, magasság és méretezési módszer (a méretezés és a vágás között) kérését.

Tartalom feltöltése

A tartalom feltöltéséhez egy fájlból, használja

contentManager.uploadContent(filePath, callback);

megadva a fájl elérési útvonalát és egy callback metódust, amely befejezéskor egy objektumot ad vissza, amely tartalmazza az mxc stílusú URI-t, ahol a feltöltött tartalom most megtalálható.

Bővebb részletekért lásd a mintaalkalmazást és a Javadoc-ot.

A mintaalkalmazást és a Javadoc-ot.