From 125f858b453afb2907e8923012875da726ee074b Mon Sep 17 00:00:00 2001 From: ramabit Date: Fri, 29 Jul 2016 16:46:48 -0300 Subject: [PATCH 1/2] add mam documentation --- documentation/extensions/mam.md | 192 ++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 documentation/extensions/mam.md diff --git a/documentation/extensions/mam.md b/documentation/extensions/mam.md new file mode 100644 index 000000000..ed0de6b03 --- /dev/null +++ b/documentation/extensions/mam.md @@ -0,0 +1,192 @@ +Message Archive Management +========================== + +Query and control an archive of messages stored on a server. + + * Check MAM support + * Query archive + * Paging + * Get form fields + * Get preferences + * Update preferences + + +**XEP related:** [XEP-0313](http://xmpp.org/extensions/xep-0313.html) + + +Get an instance of Message Archive Management Manager +----------------------------------------------------- + +``` +MamManager mamManager = MamManager.getInstanceFor(connection); +``` + + +Check MAM support +----------------- + +``` +boolean isSupported = mamManager.isSupportedByServer(); +``` + + +Query archive +------------- + +``` +MamQueryResult mamQueryResult = mamManager.queryArchive(max); +``` +*max* is an `Integer` + +or + +``` +MamQueryResult mamQueryResult = mamManager.queryArchive(withJid); +``` +*withJid* is a `Jid` + +or + +``` +MamQueryResult mamQueryResult = mamManager.queryArchive(start, end); +``` +*start* is a `Date` + +*end* is a `Date` + +or + +``` +MamQueryResult mamQueryResult = mamManager.queryArchive(additionalFields); +``` +*additionalFields* is a `List` + +or + +``` +MamQueryResult mamQueryResult = mamManager.queryArchiveWithStartDate(start); +``` +*start* is a `Date` + +or + +``` +MamQueryResult mamQueryResult = mamManager.queryArchiveWithEndDate(end); +``` +*end* is a `Date` + +or + +``` +MamQueryResult mamQueryResult = mamManager.queryArchive(max, start, end, withJid, additionalFields); +``` +*max* is an `Integer` + +*start* is a `Date` + +*end* is a `Date` + +*withJid* is a `Jid` + +*additionalFields* is a `List` + + +**Get data from mamQueryResult object** + +``` +// Get forwarded messages +List forwardedMessages = mamQueryResult.forwardedMessages; + +// Get fin IQ +MamFinIQ mamFinIQ = mamQueryResult.mamFinIQ; +``` + + +Paging +------ + +**Get a page** + +``` +MamQueryResult mamQueryResult = mamManager.page(dataForm, rsmSet); +``` +*dataForm* is a `DataForm` + +*rsmSet* is a `RSMSet` + + +**Get the next page** + +``` +MamQueryResult mamQueryResult = mamManager.pageNext(previousMamQueryResult, count); +``` +*previousMamQueryResult* is a `MamQueryResult` + +*count* is an `int` + + +**Get page before the first message saved (specific chat)** + +``` +MamQueryResult mamQueryResult = mamManager.pageBefore(chatJid, firstMessageId, max); +``` +*chatJid* is a `Jid` + +*firstMessageId* is a `String` + +*max* is an `int` + + +**Get page after the last message saved (specific chat)** + +``` +MamQueryResult mamQueryResult = mamManager.pageAfter(chatJid, lastMessageId, max); +``` +*chatJid* is a `Jid` + +*lastMessageId* is a `String` + +*max* is an `int` + + +Get form fields +--------------- + +``` +List formFields = mamManager.retrieveFormFields(); +``` + + +Get preferences +--------------- + +``` +MamPrefsResult mamPrefsResult = mamManager.retrieveArchivingPreferences(); + +// Get preferences IQ +MamPrefsIQ mamPrefs = mamPrefsResult.mamPrefs; + +// Obtain always and never list +List alwaysJids = mamPrefs.getAlwaysJids(); +List neverJids = mamPrefs.getNeverJids(); + +// Obtain default behaviour (can be 'always', 'never' or 'roster') +DefaultBehavior defaultBehavior = mamPrefs.getDefault(); + +// Get the data form +DataForm dataForm = mamPrefs.form; +``` + + +Update preferences +------------------ + +``` +MamPrefsResult mamPrefsResult = mamManager.updateArchivingPreferences(alwaysJids, neverJids, defaultBehavior); +``` +*alwaysJids* is a `List` + +*neverJids* is a `List` + +*defaultBehavior* is a `DefaultBehavior` + From 656914dcb0a9747f852e748c5f31dc16371ff729 Mon Sep 17 00:00:00 2001 From: ramabit Date: Fri, 29 Jul 2016 17:55:10 -0300 Subject: [PATCH 2/2] add mam.md in index.md --- documentation/extensions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/extensions/index.md b/documentation/extensions/index.md index 274951a34..6ab64d5de 100644 --- a/documentation/extensions/index.md +++ b/documentation/extensions/index.md @@ -85,7 +85,7 @@ Experimental Smack Extensions and currently supported XEPs of smack-experimental | [Internet of Things - Discovery](iot.md) | [XEP-0347](http://xmpp.org/extensions/xep-0347.html) | Describes how Things can be installed and discovered by their owners. | | Google GCM JSON payload | n/a | Semantically the same as XEP-0335: JSON Containers | | Client State Indication | [XEP-0352](http://xmpp.org/extensions/xep-0352.html) | A way for the client to indicate its active/inactive state. | -| Message Archive Management | [XEP-0313](http://xmpp.org/extensions/xep-0313.html) | Query and control an archive of messages stored on a server. | +| [Message Archive Management](mam.md) | [XEP-0313](http://xmpp.org/extensions/xep-0313.html) | Query and control an archive of messages stored on a server. | Legacy Smack Extensions and currently supported XEPs of smack-legacy