[JDEV] Registering with a transport?

[Peter Millard]

David -
Please reply back to win32-dev at jabber.org as this is really Win32 & JabberCOM
specific and doesn't need to be in the main JDEV list. If you aren't already
subscribed to the list, visit win32.jabber.org to sign up.

Registering w/ Agents is a process which involves a few steps.

1. Send a "get" query to the agent to fetch the registration fields.
2. Have the user fill in the fields
3. Send the "set" query back to the agent.

Using JabberCOM, you would use code like this.. (I'll try to write VB'ish code,
but this may not be 100% syntactically correct). Note this this assumes we
already have a specific JabberAgentItem object (CurrentAgentItem) which is
accessed by using the list of agents returned after the
JabberSession.Agents.Fetch call:

' Step 1, get the registration fields/info from the agent.
' Use the ID field to track what to do here..
CurrentAgentItem.GetRegister "agent_register_1"

'-------------
For step 2, Use an event handler in the OnJabberIQ event.. The agent will send
back a JabberIQ object containing all the fields for the registration process
here..

' Step 2.. Get all the fields from the JabberIQ in the OnJabberIQ Event.
Dim FieldsIt as JabberIterator        ' Use an iterator to search thru all the
JabberIQ fields
Dim Field as XMLField

if NameSpace = "jabber:iq:register" then
    Set FieldsIt = IQ.Fields
    Do While FieldsIt.HasNext
        Set Field = FieldsIt.Next    ' You may have to somehow "type-cast" this
in VB.. this
                                                ' grabs the next XMLField object
from the iterator so we can use it.
                                                ' Note also that calling .Next
also increments the iterator position
        if Field.Name = "instructions" then
            ' do something here to display the instructions
        else if Field.Name = "key" then
            ' Assign the key back to the agent so it can send it back
            ' when we send back the registration
            CurrentAgentItem.Key = Field.Data
        else if Field.Name = "registered" then
            ' do something here to indicate we are already
            ' registered with this agent
        else
            ' display the Field.Name and Field.Data in some GUI element
        end if
    end do

end if
'--------

OK, Now for Step 3, after the user fills out all the data for each field
returned in step 2, you have to "re-build" a JabberIQ object based on the GUI
elements and the data was entered. In WinJab, I use a grid to display all the
fields returned in step 2 so rebuilding the JabberIQ is simple, just iterate
through the rows adding 1 field to the new JabberIQ object per row. Obviously,
the code is going to depend a lot on what kind of GUI elements you use for the
actual registration data entry.

' Step 3 - Send registration back to the agent
Dim RegIQ as JabberIQ

Set RegIQ = JabberSession.CreateIQ

For i = 0 to MyGrid.RowCount - 1 do
    RegIQ.SetField(MyGrid.Cells[0, i], MyGrid.Cells[1, i])
Next i
CurrentAgentItem.SetRegister "agent_register_2", RegIQ

'-----------
That's about it... once the registration is complete you will most likely get a
"result" <iq> tag back into either the OnJabberIQ event or the OnUnhandledQuery
event... Depending on the Agent, you may also get other Jabber events like
subscription requests, etc..

Hope this helps demonstrate the power & flexibility of the Agents Interface.
Also note that agents can have "Sub-Agents"... All of that capability is
"exposed" through each JabberAgentItem.Agents interface. Thus the AgentItem is
inherently recursive (fun :)... so you can call CurrentAgentItem.Agents.Fetch,
etc. The use of specific "ID" attributes is VERY important to track which sets,
gets, results are tied to which agents.


--------------------------------
Peter Millard
Software Engineer, Vantek Corp.
peter at vantek-corp.com
http://www.vantek-corp.com