Update Documentation

[Mazianni]

Hullo.

I am attempting to use this library, but running into the issue that there is almost no accurate documentation (the examples on the website, for example, are a completely incorrect pattern for receiving messages). I have barely been able to figure out how to use this to join rooms, etc, let alone actually figure out what stanzas are coming in and how to handle them.

[agnauck]

I don't see whats wrong with the docs of receiving messages here:
https://xmppdotnet.org/docs/receiving-messages/

You can find excellent examples for all stanzas in the official XMPP docs, the RFCs and all the extension protocols.
Then mapping those smaple stanzas to the XmppDotNet docs should not be that hard. When you have specific issues then just ask and I will extend the docs as well.

Below is a join room snipped which I used in a poject. It joins a room without requesting any history messages (MaxStanzas = 0). Because I usually request the messages from the archive when required.

Please study also the MUC extensions at:
https://xmpp.org/extensions/xep-0045.html

public async Task<XmppXElement> EnterRoomAsync(string channel, string nickname)
{
    var joinRoom = new Presence
    {
        To = $"{channel}/{nickname}",
        Muc = new X
        {
            History = new History
            {
                MaxStanzas = 0
            }
        },
        Caps = caps.ClientCapabilities
    };

    bool Predicate(XmppXElement e) 
        => e.OfType<Presence>() 
           && e.Cast<Presence>().From.Equals(joinRoom.To, new FullJidComparer());

    return await xmppClient.SendAsync(joinRoom, Predicate);
}

[Mazianni]

The existing LINQ pattern on the website documentation does not appear to be usable with the current NuGet packages (XMPPClient implements XmppXElementReceived, not XmppXElementStreamObserver). The Linq syntax is wrong for that, since you can't do Where() and filter for specific message types - you have to do that in a observer somewhere.

It's just the little things, honestly, and having to look at projects based off Matrix to figure out how to do something that's really not super friendly for me. I'm trying to understand if XmppDotNet parses the incoming stanzas into a class (i.e, Message) that I can access an object or if I need to transform the data from a received XElement to further use myself (the answer to that being, yes, as far as I can see).

[agnauck]

yes, XmppDotNet builds custom objects that are derived from XElement while it parses the stream. Of course you get custom Elements only for the stanzas that its aware of. Otherwise you get a XmppXElement which is derived from a dotnet XElement

Here is a snippet that looks for group chat messages:

using XmppMessage = XmppDotNet.Xmpp.Client.Message;

// subject messages
xmppClient
    .XmppXElementReceived
    .Where(el => el is XmppMessage {Type: MessageType.GroupChat, Subject: { }})
    .Select(el => el as XmppMessage)
    .Subscribe(msg =>
    {
        // do something with the message
    });

I will check the docs when I get some time. I assume they were not updated after a reactor where the obsever name changed. Sorry about that.
I also plan to move the docs repo to Github as well, so that other can contribte to them as well

[agnauck]

I have pushed an update to the docs. The mentioned issue should be corrected.
I have also migrated the docs to a repo on Github and setup the actions for autoated publishing. The repo is still private.
I have not made a final desicion yet whether the docs should be added to this repo, or remain in their own repo.
Will be public soon then...

[Mazianni]

Good to hear! I look forward to it.