Invitation

Volity requires a standard mechanism that allows a [the Jabber protocol's method for inviting people into MUCs], but for Volity's purposes, this is both insufficient (as it doesn't carry any information about the table, other than its JID) and dangerous (as it could be received and interpreted by a standard Jabber client, making you end up with the confusing situation of "normal" Jabber users sitting at the table, interpreting it as an ordinary MUC).

Therefore Volity instead uses the mechanism described here to allow players to invite other players to their tables.

Usage summary

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.

• If the referee sees a resource string in the argument of 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.
• If there is no resource, the referee will send a <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.

RPC Requests

volity.invite_player (player_JID)

volity.invite_player (player_JID, message)

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).

volity.receive_invitation (invitation_struct)

Received by a player, from a (presumably heretofore unknown) referee.

The one argument is an RPC struct, which must contain the following fields:

player

The JID of the player extending the invitation.

table

The JID of the table the receiver has been invited to join.

referee

The JID of that table's referee.

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):

parlor

The JID of that table's parlor.

ruleset

The URI of that server's ruleset.

name

The (non-internationalized) name of the game.

Finally, the struct may also contain any or all of these fields:

message

A text message that accompanies the invitation.

Message Invitations

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>