Next: , Previous: Listening for new requests, Up: Hacking and extending

16.5 Sending new requests

To send an IQ request, use jabber-send-iq. It will generate an id, and create a mapping for it for use when the response comes. The syntax is:

     (jabber-send-iq connection to type query
                     success-callback success-closure
                     failure-callback failure-closure)

success-callback will be called if the response is of type ‘result’, and failure-callback will be called if the response is of type ‘error’. Both callbacks take three arguments, the connection object, the IQ stanza of the response, and the corresponding closure item earlier passed to jabber-send-iq.

Two standard callbacks are provided. jabber-report-success takes a string as closure item, and reports success or failure in the echo area by appending either ‘succeeded’ or ‘failed’ to the string. jabber-process-data prepares a browse buffer. If its closure argument is a function, it calls that function with point in this browse buffer. If it's a string, it prints that string along with the error message in the IQ response. If it's anything else (e.g. nil), it just dumps the XML in the browse buffer.

Examples follow. This is the hypothetical Jabber protocol “frob”, for which only success report is needed:

     (jabber-send-iq connection
                     "" "set"
                     '(query ((xmlns . "frob")))
                     'jabber-report-success "Frobbing"
                     'jabber-report-success "Frobbing")

This will print “Frobbing succeeded” or “Frobbing failed: reason”, respectively, in the echo area.

The protocol “investigate” needs to parse results and show them in a browse buffer:

     (jabber-send-iq connection
                     "" "get"
                     '(query ((xmlns . "investigate")))
                     'jabber-process-data 'jabber-process-investigate
                     'jabber-process-data "Investigation failed")

Of course, the previous example could have used jabber-report-success for the error message. It's a matter of UI taste.