Missing documentation

[arthef]

There is no documentation or example code on how to retrieve user's roster.

Please add code example on retrieving user's roster as well as other typical XMPP use cases:

• roster
• presence status for contact
• own user vcard
• contact vcard

[bmalkow]

Before I finish documentation, here you have short examples.

Just after connection is established, Halcyon asks for roster itself. You no need to do anything.
It is possible you will implement own roster storage with versioning. Here is short note about it.

	// Registering events listener before you connect to server
	client.eventBus.register<RosterEvent>(RosterEvent.TYPE) { event ->
		when (event) {
			is RosterEvent.ItemAdded -> println("Item ${event.item.jid} was pushed to local roster store")
			is RosterEvent.ItemUpdated -> println("Item ${event.item.jid} was updated in local roster store")
			is RosterEvent.ItemRemoved -> println("Item ${event.item.jid} was removed from local roster store")
		}
	}
	val rosterModule = client.getModule<RosterModule>(RosterModule.TYPE)!!
	val presenceModule = client.getModule<PresenceModule>(PresenceModule.TYPE)!!

	// Adding item to roster
	rosterModule.addItem(RosterItem("rob@example.com".toBareJID(), "Rob Doe")).response {
		it.onSuccess {
			println("Request is accepted by server. Listen for ItemAdded event.")
		}
	}.send()

	// Updating item in roster
	val item = rosterModule.store.getItem("rob@example.com".toBareJID())!!
	val itemNew = item.copy(name = "Rob")
	rosterModule.addItem(itemNew).response {
		it.onSuccess {
			println("Request is accepted by server. Listen for ItemUpdated event.")
		}
	}.send()

	// Removing item from roster
	rosterModule.deleteItem("rob@example.com".toBareJID()).response {
		it.onSuccess {
			println("Request is accepted by server. Listen for ItemRemoved event.")
		}
	}.send()

Simple presence example:

	client.eventBus.register<ContactChangeStatusEvent> { event->
		// $presence is "best presence for contact", not just received presence. Best presence is presence with high priority.
		println("This is presence of contact ${event.jid}: ${event.presence}")
	}

	// Displaying presence of all items from roster:
	rosterModule.getAllItems().forEach { rosterItem ->
		val presence: Presence? = presenceModule.getBestPresenceOf(rosterItem.jid)
	}

Note, that presence may be null. You have to calculate "logic presence state" from presence stanza. You may use code like this:

	enum class Status {
		Away,
		Chat,
		Dnd,
		Error,
		Offline,
		Online,
		Unknown,
		Xa,
		None
	}

	private fun calculateStatus(presence: Presence?): Status {
		if (presence == null) return Status.Offline
		val type = presence.type
		val show = presence.show
		return when (type) {
			PresenceType.Error -> Status.Error
			PresenceType.Unavailable -> Status.Offline
			null -> when (show) {
				null -> Status.Online
				Show.XA -> Status.Xa
				Show.DnD -> Status.Dnd
				Show.Away -> Status.Away
				Show.Chat -> Status.Chat
			}
			else -> Status.Unknown
		}
	}

I will add similar code to library.

[arthef]

Thank you. What about vCard? What would be the best code to request vCard for each roster item that is being retrieved?