Therefore Volity instead uses the mechanism described here to allow players to invite other players to their tables.
The inviting player makes an volity.invite_player
request to the referee (not the player it wishes to invite; the recipient's JID goes into the arguments).
The inviting player's client should try to discover a resource string for the recipient -- preferably a resource of a Volity client. (It may use Entity Capabilities in roster presence, or observe presence in a Volity game or lobby.) If it succeeds, it should include this resource in the volity.invite_player
JID. If not, it should send a bare JID.
volity.invite_player
, it will send a volity.receive_invitation
RPC to that JID. (Recall that Jabber-RPC calls must be made to full JIDs.) Any RPC or stanza errors will be reported back to the inviting player as a failure token array: ("volity.relay_failed", "literal.JID")
, where JID is the full JID that the invitation could not be delivered to.
<message>
with a Volity extension. There is no response to a <message>
stanza, so the referee should report success back to the inviting player.
(A note on error handling: A client that sends volity.invite_player
with a full JID, and receives a failure token, may well want to retry with a bare JID. Since messages do not produce errors, there will be no second retry.)
In either case, the referee also makes any [configuration changes to the MUC] that are necessary to allow the invited player to join.
The client must be prepared to receive an invitation in either RPC or message format. If it's a client application (and not a ronin), it will at this point present its user with an interface to accept or reject the invitation. If accepted, the player uses the UI finder to get the appropriate UI file (for the ruleset URI of the table was included among the invitation's argments) and then joins the existing MUC.
Received by a referee, from a player seated at the same table. If a referee receives this request from any other entity, it must return a fault.
Indicates that the sending player wishes to invite the player with the given JID to the table. The optional second argument is a text message to be included with the invitation.
The player named in the first argument should be someone not already at the table; otherwise, the ref should return a fault.
Returns a true value when the invitation has been successfully sent (with no implication as to whether it was accepted or not).
Received by a player, from a (presumably heretofore unknown) referee.
The one argument is an RPC struct, which must contain the following fields:
It should also contain these fields (as this information should be available by discoing the referee, but there's probably no reason to make the receiver do more work if the sender has the info handy):
Finally, the struct may also contain any or all of these fields:
A <message>
invitation is directed to a user (a bare JID) and not to a specific connection. It may be received by any Jabber client. Therefore, it should contain plain text describing the invitation, followed by a Jabber data form containing the invitation fields (as described above).
The data form is wrapped in an <volity xmlns="http://volity.org/protocol/form">
element. The form itself should have a FORM_TYPE of http://volity.org/protocol/form/invite
.
Sample message:
<message id="jc2s12" to="zarf@volity.net" from="zarf-treehouse@volity.net/ref_24994_1142910091" > <body>[zarf-volity-test4@volity.net has invited you to join a game of Treehouse at table ref_24994_1142910091@conference.volity.net.]</body> <volity xmlns="http://volity.org/protocol/form"> <x xmlns="jabber:x:data" type="result"> <field var="FORM_TYPE" type="hidden"> <value>http://volity.org/protocol/form/invite</value> </field> <field var="referee"> <value>zarf-treehouse@volity.net/ref_24994_1142910091</value> </field> <field var="name"> <value>Treehouse</value> </field> <field var="player"> <value>belford@volity.net/javolinQFUDFG</value> </field> <field var="parlor"> <value>zarf-treehouse@volity.net/volity</value> </field> <field var="ruleset"> <value>http://volity.org/games/treehouse/</value> </field> <field var="table"> <value>ref_24994_1142910091@conference.volity.net</value> </field> </x> </volity> </message>