1. Introduction

Documentation of the XMPP-RTMP gateway currently running at rtmp://knecht.symlynx.com/xmpp

Design Requirements

2. Connection Managment

connecting

		nc.call("xmpp_connect", new Responder(xmpp_connected),
			{ username : "nodepartofjid",
			  domain   : "domainpartofjid",
			  password : "plaintextpassword",
			  resource : "resourcething"
			  } );
		...
	private function xmpp_connected(success : Number):void {

	}
If the connect is successful, the responder will be called with success=1.0.

disconnecting

		nc.call("xmpp_disconnect", new Responder(xmpp_disconnected));
		...

	private function xmpp_disconnected(reason : String):void {

	}
Note that xmpp_disconnected may also be called by the server when your connection to the server is closed.

3. Sending Stanzas

the first argument is the string "xmpp", which calls the xmpp send method on the server. the second argument should be null, unless the stanza is an iq stanza of type get or set and a result is expected. the third argument to the call is the stanza type which should be either "message", "presence" or "iq". the fourth argument is a object which may contain the common toplevel attributes of the stanza as defined in section 9.1 of RFC 3920. Note that setting "from" is futile, it will be overridden by the server anyway. The fifth argument is a string containing the innerxml body of the stanza. It is highly recommended that this is valid XML, otherwise your connection to the xmpp server will be terminated.

sending a message stanza:

		nc.call("xmpp", null, "message",
			{ to  : "someuser@example.com/theresource",
			  type: "chat"
			  },
			  <body>hello world</body>.toXMLString());

sending a presence stanza:

		nc.call("xmpp", null, "presence",
			{ },
			<show>debugging rtmp2xmpp gateway</show>.toXMLString());
When sending an iq stanza, it is possible to set a responder. This responder will be called with a single object, an array containing an object of toplevel attributes as described above and the raw innerxml body of the stanza as a string.

sending an iq stanza with responder:

		nc.call("xmpp", new Responder(roster_get), "iq",
			{ type: "get"
			},
			<query xmlns='jabber:iq:roster'/>.toXMLString());
	...
        public function roster_get(result:Object):void {
                // responders can only have a single argument unfortunately
                var attrib : Object = result[0];
                var rawbody : Object = result[1];
                var body : XMLList = new XMLList(rawbody);

                trace("rosterget response!");
		trace(attrib.toString());
                trace(rawbody.toString());
        }

4. Messaging Callbacks

The server will call certain functions in the object referred to by the NetConnection.client property.

Necessary callbacks

        public function xmpp_message(attrib : Object, rawbody : String):void {
                var body : XMLList = new XMLList(rawbody);
                trace("message from " + attrib.from + ": " + body.toXMLString());
        }

        public function xmpp_presence(attrib : Object, rawbody : String):void {
                var body : XMLList = new XMLList(rawbody);
                trace("presence from " + attrib.from + ": " + rawbody.toString());
        }

        public function xmpp_iq(attrib : Object, rawbody : String):void {
                var body : XMLList = new XMLList(rawbody);
	}

"attrib" is a Object which may contain any "common attribute" of a toplevel xmpp stanza as defined in section 9.1 of RFC 3920. rawbody is the innerxml body of the stanza as a string. It should be casted to a XMLList.

Note: you MUST send a reply for iq stanzas of type get or set. The bare minimum for this is replying with a not-implemented error as follows:

		nc.call("xmpp", null, "iq",
			{ to: attrib.from,
			  id: attrib.id,
			  type: "error"
			  },
			 <error type='cancel'>
			 <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
			 </error>.toXMLString()
		       );

5. Interaction with Jingle

TBD
Notes: set framesPerPacket property of Microphone to 1 and codec property to "SPEEX".
Might be possible to map API to NetStream play and publish

Legal Notices

Copyright

This Specification is copyright © 2009 by the respective authors.

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the author has been advised of the possibility of such damages.

Author Information

Philipp Hancke

Email: fippo@mail.symlynX.com
psyc: psyc://goodadvice.pages.de/~fippo
JID: fippo@goodadvice.pages.de

Metadata

Version: 0.1-tmp
Last Updated: 2009-10-03